Skip to content

Add shadow root reference target information #42323

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
meyerweb wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Add shadow root reference target information #42323

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2aab908
Update wording
meyerweb Dec 9, 2025
5892a7d
Merge branch 'main' into referenceTarget
meyerweb Dec 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions files/en-us/web/api/element/attachshadow/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,9 @@ attachShadow(options)
- : A boolean that, when set to `true`, specifies behavior that mitigates custom element issues around focusability.
When a non-focusable part of the shadow DOM is clicked, the first focusable part is given focus, and the shadow host is given any available `:focus` styling. Its default value is `false`.

- `referenceTarget` {{Optional_Inline}} {{Experimental_Inline}}
- : A string specifying the _reference target_ of any element references made against the host element of the shadow DOM tree. The reference target must be an element held within the shadow DOM.
Copy link

@alice alice Dec 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- : A string specifying the _reference target_ of any element references made against the host element of the shadow DOM tree. The reference target must be an element held within the shadow DOM.
- : A string value that indicates the effective target of any element reference made against the shadow host from outside the host element. The value should be the ID of an element inside the shadow DOM. If set, target references to the host element from outside the shadow DOM will cause the referenced target element to become the effective target of the reference to the host element.


- `serializable` {{Optional_Inline}}
- : A boolean that, when set to `true`, indicates that the shadow root is serializable.
If set, the shadow root may be serialized by calling the {{DOMxRef('Element.getHTML()')}} or {{DOMxRef('ShadowRoot.getHTML()')}} methods with the `options.serializableShadowRoots` parameter set `true`.
Expand Down
2 changes: 2 additions & 0 deletions files/en-us/web/api/shadowroot/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,8 @@ You can retrieve a reference to an element's shadow root using its {{domxref("El
- {{DOMxRef("ShadowRoot.pointerLockElement")}} {{ReadOnlyInline}}
- : Returns the {{DOMxRef('Element')}} set as the target for mouse events while the pointer is locked.
`null` if lock is pending, pointer is unlocked, or if the target is in another tree.
- `ShadowRoot.referenceTarget` {{ReadOnlyInline}} {{Experimental_Inline}}
- : A string value that indicates the effective target of any element reference made against the shadow host from outside the host element.
Copy link

@alice alice Dec 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- : A string value that indicates the effective target of any element reference made against the shadow host from outside the host element.
- : A string value that indicates the effective target of any element reference made against the shadow host from outside the host element. The value should be the ID of an element inside the shadow DOM. If set, target references to the host element from outside the shadow DOM will cause the referenced target element to become the effective target of the reference to the host element.

- {{DOMxRef("ShadowRoot.serializable")}} {{ReadOnlyInline}}
- : A boolean that indicates whether the shadow root is serializable.
A serializable shadow root inside an element will be serialized by {{DOMxRef('Element.getHTML()')}} or {{DOMxRef('ShadowRoot.getHTML()')}} when its [`options.serializableShadowRoots`](/en-US/docs/Web/API/Element/getHTML#serializableshadowroots) parameter is set `true`.
Expand Down
3 changes: 3 additions & 0 deletions files/en-us/web/html/reference/elements/template/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,9 @@ This element includes the [global attributes](/en-US/docs/Web/HTML/Reference/Glo
If this is set and a non-focusable element in the shadow tree is selected, then focus is delegated to the first focusable element in the tree.
The value defaults to `false`.

- `shadowrootreferencetarget` {{Experimental_Inline}}
- : Sets the value of the `referenceTarget` property of a [`ShadowRoot`](/en-US/docs/Web/API/ShadowRoot) created using this element. The value should be the ID of an element inside the shadow DOM. If set, target references to the host element from outside the shadow DOM will cause the referenced target element to become the effective target of the reference to the host element.
Copy link

@alice alice Dec 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The value should be the ID of an element inside the shadow DOM. If set, target references to the host element from outside the shadow DOM will cause the referenced target element to become the effective target of the reference to the host element.

I think this wording is great, how would you feel about including it for each of these brief descriptions?


- `shadowrootserializable`
- : Sets the value of the [`serializable`](/en-US/docs/Web/API/ShadowRoot/serializable) property of a [`ShadowRoot`](/en-US/docs/Web/API/ShadowRoot) created using this element to `true`.
If set, the shadow root may be serialized by calling the {{DOMxRef('Element.getHTML()')}} or {{DOMxRef('ShadowRoot.getHTML()')}} methods with the `options.serializableShadowRoots` parameter set `true`.
Expand Down