Add reference target #10995

dandclark · 2025-02-05T01:39:54Z

Reference Target allows authors to specify an element inside a shadow root to be the target of any ID references referring to the host element. This would enable IDREF attributes such as for and aria-labelledby to refer to elements inside a component's shadow DOM while maintaining encapsulation of the internal details of the shadow DOM.

See the reference target explainer.

At a high level, the spec change consists of these parts:

Define the concept of "resolving the reference target" on an element, following an IDREF from a host element to its target in the shadow, and potentially recursing.
Update the get-the-attr-associated-element algorithm (and its array-of-elements form) to follow reference target.
Centralize the definitions of ID reference attributes and list-of-ID-reference attributes as "element reference" and "set of element reference" attributes instead of repeating these definitions throughout the spec.
Update uses of ID throughout the spec, where applicable, to use the new reference-target-aware get-the-attr-associated-element.
Avoid exposing reference target elements in shadows from element-returning IDL properties by retargeting the result before returning.

See also the corresponding whatwg/dom#1353 which adds the definition of reference target used in this PR.

At least two implementers are interested (and none opposed):
- Reference Target for Cross-Root ARIA mozilla/standards-positions#1035 (no position stated yet)
- Reference Target for Cross-Root ARIA WebKit/standards-positions#356 (no position stated yet)
Tests are written and can be reviewed and commented upon at:
- https://wpt.fyi/results/shadow-dom/reference-target/tentative?label=experimental&label=master&aligned (still tentative)
- PR to make non-tentative: Make reference target non-tentative web-platform-tests/wpt#51213
Implementation bugs are filed:
- Chromium: https://issues.chromium.org/issues/346835896/
- Gecko: https://bugzilla.mozilla.org/show_bug.cgi?id=1952585
- WebKit: https://bugs.webkit.org/show_bug.cgi?id=285634
Corresponding HTML AAM & ARIA in HTML issues & PRs: Opened Editorial: Point to "element reference attribute" definitions in HTML for IDREF attributes w3c/aria#2474; there is still some discussion to be had about what other ARIA/AAM changes might be needed.
MDN issue is filed: (I'll do this once the API name and IDL is finalized)
The top of this comment includes a clear commit message to use.

(See WHATWG Working Mode: Changes for more details.)

/common-dom-interfaces.html ( diff )
/common-microsyntaxes.html ( diff )
/dom.html ( diff )
/form-control-infrastructure.html ( diff )
/form-elements.html ( diff )
/forms.html ( diff )
/iframe-embed-object.html ( diff )
/index.html ( diff )
/indices.html ( diff )
/infrastructure.html ( diff )
/input.html ( diff )
/microdata.html ( diff )
/parsing.html ( diff )
/popover.html ( diff )
/scripting.html ( diff )
/tables.html ( diff )

… to shadow creation

…eference-target-attr-associated-element

…roperty

…ibute concepts.

Refactoring, and adding output-for and popover

…d make some tweaks in the Reflection section

Collapse most of the 'reset the form owner' checks into one that just watches for changes to the form(attr)-associated-element.

dandclark · 2025-03-18T00:37:25Z

@annevk, @domenic, this isn't quite ready to land yet as there are still a few open questions to sort out (at least WICG/webcomponents#1087 and WICG/webcomponents#1093), plus missing implementor positions. But I don't expect most of the mechanics in this PR to change, so I think it would be great to get feedback on whether the approach we've used here is agreeable.

See also whatwg/dom#1353

Thanks!

alice · 2025-03-19T00:49:42Z

There's also a WIP PR against ARIA to account for these changes: w3c/aria#2474

There are some open questions being discussed there on exactly how to refer to the HTML concepts, since ARIA needs to be language-independent, but it will certainly refer to these spec concepts in some form.

…ssed

…IDL attributes

lukewarlow

This should be updated to make use of the new [Reflect] syntax.

source

…ithm

dandclark · 2025-08-06T21:38:26Z

This should be updated to make use of the new [Reflect] syntax.

Thanks @lukewarlow! Fixed now (it wouldn't let me merge the suggestions directly due to merge conflicts).

lukewarlow · 2025-08-06T21:42:24Z

I'm not sure how GitHub actually lets you dismiss change suggestions but consider this me dropping my change suggestions as they've been resolved :)

keithamus

I've done an initial review pass, got about half way, but I thought I'd provide my review commentary so far because I think if I continue I may end up repeating themes.

Some meta commentary:

I think another formatting pass needs to be done.
I am a little worried about the retargeting steps, I wonder if this can be simplified to avoid retargeting and to resolve a reference target where necessary.

keithamus · 2025-08-28T13:54:33Z

source

+
+   <li><p>If no such element exists, return null.</p></li>
+
+   <li><p>Return the result of <span data-x="resolve-the-reference-target">resolving the reference


Can you help me understand how this set of steps avoids exposing elements in the shadow root to code calling the IDL bindings?

It seems as though there's nothing in the spec that says "when script calls this, it should not resolve the reference target".

The way I would interpret this is that IDL should return the resolved reference target, which is obviously wrong as it would expose ShadowDOM elements to script.

I'm surprised this has is written this way, I would have imagined we would not change reflection rules, and instead wherever we look at an element reflecting attribute, we would have an additional step to resolve the reference target there.

keithamus · 2025-08-28T13:59:27Z

source

+   <span>shadow root</span>'s <span>reference target</span> is null, return <var>element</var>.</p>
+   </li>
+
+   <li><p>Let <var>referenceTarget</var> be the value of <var>element</var>'s <span>shadow


I was a little confused here about what referenceTarget represents. A non-binding suggestion: rename this to perhaps referenceTargetId or just targetId or similar?

keithamus · 2025-08-28T14:02:56Z

source

+   <li><p>Let <var>candidate</var> be the first element in <var>element</var>'s <span>shadow
+   root</span> whose <span data-x="concept-id">ID</span> matches <var>referenceTarget</var>.</p>
+   </li>
+
+   <li><p>If no such element exists, return null.</p></li>


These steps being disjoint were confusing to me, as step 4 read in isolation makes no reference to variables or some such. I think they'd be better joined:

Suggested change

<li>Let <var>candidate</var> be the first element in <var>element</var>'s shadow

root whose ID matches <var>referenceTarget</var>.

</li>

<li>If no such element exists, return null.</li>

<li>Let <var>candidate</var> be the first element in <var>element</var>'s shadow

root whose ID matches <var>referenceTarget</var>. If no

such element exists, then return null.</li>

Or alternatively:

Suggested change

<li>Let <var>candidate</var> be the first element in <var>element</var>'s shadow

root whose ID matches <var>referenceTarget</var>.

</li>

<li>If no such element exists, return null.</li>

<li>Let <var>candidate</var> be the first element in <var>element</var>'s shadow

root whose ID matches <var>referenceTarget</var>. If no

such element exists, then instead let <var>element</var> be null.</li>

<li>If <var>element</var> is null, then return null</li>

keithamus · 2025-08-28T14:03:37Z

source

+   <li><p>Return the result of <span data-x="resolve-the-reference-target">resolving the reference
+   target</span> on <var>candidate</var>.
+   </p></li>


Formatting:

Suggested change

<li>Return the result of resolving the reference

target on <var>candidate</var>.

</li>

<li>Return the result of resolving the reference

target on <var>candidate</var>.</li>

keithamus · 2025-08-28T14:04:46Z

source

+  <p><dfn data-x="element reference attribute" data-lt="element reference" export>
+  Element reference attributes</dfn> refer to one or more Elements in the document. When specified
+  as content attributes, <span
+  data-x="element reference attribute">element reference attributes</span> refer to other Elements
+  via their <span data-x="concept-ID">ID</span>s.


Formatting is not right here, I think, but also it's missing a :

Suggested change

<dfn data-x="element reference attribute" data-lt="element reference" export>

Element reference attributes</dfn> refer to one or more Elements in the document. When specified

as content attributes, element reference attributes refer to other Elements

via their IDs.

<dfn data-x="element reference attribute" data-lt="element reference" export>Element reference

attributes</dfn> refer to one or more Elements in the document. When specified as content

attributes, element reference attributes refer

to other Elements via their IDs.

keithamus · 2025-08-28T14:14:00Z

source

+      </ol>
+     </li>
+    </ol>
+


Double line break:

Suggested change

keithamus · 2025-08-28T14:14:46Z

source

+    <p class="note">An element will only have
+    <span data-x="explicitly set attr-elements">explicitly-set <var>attr</var>-elements</span> if it
+    has an IDL attribute with type <code
+    data-x="">FrozenArray&lt;<var>T</var>&gt;?</code>, where <var>T</var> is either
+    <code>Element</code> or an interface that inherits from <code>Element</code>, which
+    <span data-x="reflect">reflects</span> <var>attr</var>.</p>


Formatting seems wonky here, maybe this is better:

Suggested change

An element will only have

explicitly-set <var>attr</var>-elements if it

has an IDL attribute with type <code

data-x="">FrozenArray<<var>T</var>>?</code>, where <var>T</var> is either

<code>Element</code> or an interface that inherits from <code>Element</code>, which

reflects <var>attr</var>.

An element will only have

explicitly-set <var>attr</var>-elements if it

has an IDL attribute with type <code data-x="">FrozenArray<<var>T</var>>?</code>, where

<var>T</var> is either <code>Element</code> or an interface that inherits from

<code>Element</code>, which reflects <var>attr</var>.

keithamus · 2025-08-28T14:22:10Z

source

+   <li>
+    <p><span data-x="list iterate">For each</span> <var>candidate</var> in <var>candidates</var>:
+    </p>
+
+    <ol>
+     <li><p>Let <var>resolvedCandidate</var> be the result of
+     <span data-x="resolve-the-reference-target">resolving the reference target</span> on
+     <var>candidate</var>.</p></li>
+
+     <li><p>If <var>resolvedCandidate</var> is not null, append <var>resolvedCandidate</var> to
+     <var>resolvedCandidates</var>.</p></li>
+    </ol>
+   </li>
+
+   <li><p>Return <var>resolvedCandidates</var>.</p></li>
+  </ol>


Why do we make a list of candidates to then re-iterate the list and resolve them? Would it not be easier to resolve each candidate during the for each steps so that candidates is a list of resolvedCandidates?

keithamus · 2025-08-28T14:25:41Z

source

+     <li><p>Let <var>candidate</var> be the result of running <span>this</span>'s
+     <span data-x="get the attr-associated element">get the <var>attr</var>-associated
+     element</span>.</p>


Oh I see. IDL reflections take the attr-resolved reference target and then retarget against element. This seems a little like extra work for no payoff. Are there concrete reasons to do this, rather than having attr-resolved elements return the element, and then in each spec resolve the reference target?

I'm also not sure retargeting against element is always going to consistently give the same result as the old way of handling things. This feels awkward to me.

lukewarlow · 2025-08-28T14:40:56Z

source

-  readonly attribute <span>HTMLFormElement</span>? <span data-x="dom-label-form">form</span>;
+  readonly attribute <span>HTMLElement</span>? <span data-x="dom-label-form">form</span>;


Would it be observable? You'd still end up with a form element returned in all existing code right?

Current code expects a form element or null. This change would mean it could get some other thing, which may be surprising.

An example of a potential surprise: if (foo.form) new FormData(foo.form) would now throw an error.

Yeah but you'd only get that if you start using this new referencetarget? So it's not really a compat issue as I understand it?

I guess "web compatible" is the wrong term here. Old sites wouldn't break, but the change here might cause a surprise for actively maintained websites.

I guess I'll mark as resolved.

smaug---- · 2025-09-01T16:51:48Z

source

+    <ol>
+     <li>
+      <p><span data-x="list iterate">For each</span> <var>attrElement</var> in
+      <var>reflectedTarget</var>'s <span>explicitly set <var>attr</var>-elements</span>:</p>


What is reflectedTarget here?

Suggested change

<var>reflectedTarget</var>'s explicitly set <var>attr</var>-elements:

<var>element</var>'s explicitly set <var>attr</var>-elements:

smaug---- · 2025-09-01T17:10:30Z

source

-  <span>tree</span>.</p>
+  a valid <span>single element reference</span> attribute
+  <span data-x="single-element-reference-refers-to">referring to</span> a <code>form</code>
+  element.</p>


This isn't perhaps super clear. I think this means that the final element from single element reference should be a form element

lukewarlow · 2025-09-01T17:20:05Z

source

+   <li><p>Let <var>candidates</var> be an empty <span>list</span>.</p></li>
+
+   <li>
+    <p>If <var>element</var>'s has an <span>explicitly set <var>attr</var>-elements</span> which


This isn't grammatically correct. Based on the which I'm guessing the has is correct so drop the 's

Suggested change

If <var>element</var>'s has an explicitly set <var>attr</var>-elements which

If <var>element</var> has an explicitly set <var>attr</var>-elements which

smaug---- · 2025-09-01T17:28:24Z

source

-  order</span> is a <span data-x="category-label">labelable element</span>, then that element is the
-  <code>label</code> element's <span>labeled control</span>.</span></p>
+  attribute is specified, the attribute's value must be the a valid <span>single element
+  reference</span> attribute.</p>


But the final result of single element reference doesn't need to be labelable element?

smaug---- · 2025-09-01T17:45:08Z

source

+     <var>descendant</var>.</p></li>
+
+     <li><p>If <var>candidate</var> is a <span data-x="category-label">labelable element</span>,
+     return <var>candidate</var>.</p></li>


This handling of descendants feels a bit surprising, but I don't have strong opinions, and the behavior is probably fine.

smaug---- · 2025-09-01T18:29:35Z

source

-  data-x="attr-popover">popover</code> attribute in the same <span>tree</span> as the <span
-  data-x="concept-button">button</span> with the <code
+  be a valid <span>single element reference</span> attribute
+  <span data-x="single-element-reference-refers-to">referring to</span> an element with the <code


Is this correct? The old text requires an element with popover attribute.

smaug---- · 2025-09-01T18:34:04Z

source

@@ -65213,6 +65362,7 @@ interface <dfn interface>HTMLTemplateElement</dfn> : <span>HTMLElement</span> {
  [<span>CEReactions</span>, <span data-x="xattr-Reflect">Reflect</span>] attribute boolean <dfn attribute for="HTMLTemplateElement" data-x="dom-template-shadowrootclonable">shadowRootClonable</dfn>;
  [<span>CEReactions</span>, <span data-x="xattr-Reflect">Reflect</span>] attribute boolean <dfn attribute for="HTMLTemplateElement" data-x="dom-template-shadowRootSerializable">shadowRootSerializable</dfn>;
  [<span>CEReactions</span>, <span data-x="xattr-Reflect">Reflect</span>] attribute DOMString <dfn attribute for="HTMLTemplateElement" data-x="dom-template-shadowRootCustomElementRegistry">shadowRootCustomElementRegistry</dfn>;
+  [<span>CEReactions</span>, <span data-x="xattr-Reflect">Reflect</span>] attribute DOMString? <dfn attribute for="HTMLTemplateElement" data-x="dom-template-shadowRootReferenceTarget">shadowRootReferenceTarget</dfn>;


Why is shadowRootReferenceTarget nullable?

alice and others added 5 commits February 4, 2025 15:42

Begin exploring how to specify what effect referenceTarget has.

a9d0db4

Add shadowrootreferencetarget attribute to template, plumb it through…

1ade6e0

… to shadow creation

Merge remote-tracking branch 'alice/referenceTarget' into dandclark/r…

13eea97

…eference-target-attr-associated-element

Use 'reference target' internal definition on Shadow instead of IDL p…

cd247ab

…roperty

Implicit label association accounts for reference target

3062978

dandclark changed the title ~~Add shadowrootreferencetarget attribute to template~~ Add reference target Feb 6, 2025

dandclark and others added 4 commits February 6, 2025 00:44

Don't directly nest <ol>s

1bcd135

Actually return the resolved reference target from labeled control algo

85e7f19

Add a section about multiple element reference attributes

9fe4ad6

Merge branch 'whatwg:main' into dandclark/reference-target

29c167c

rniwa mentioned this pull request Feb 14, 2025

Add support for referenceTarget. WebKit/WebKit#39742

Merged

dandclark and others added 11 commits February 18, 2025 19:36

Pull in Alice's multiple element reference attributes change

a652c51

Fix element reference attribute definition

28acb5c

Update HTMLLabelElement control and form properties

d6fbcfd

Update the HTMLInputElement.list attribute

e964930

Update headers property

004f71b

Update form association

7f84015

Define headers and list attributes in terms of element reference attr…

7c5c799

…ibute concepts.

Update output-for and popover, and reword definitions

d35e5af

Merge pull request #3 from alice/dandclark/reference-target

27f5793

Refactoring, and adding output-for and popover

Update itemref attribute

c99b613

Update attributes table

89f72a4

This was referenced Mar 7, 2025

Add reference target to shadow root whatwg/dom#1353

Open

Make reference target non-tentative web-platform-tests/wpt#51213

Draft

Editorial: Point to "element reference attribute" definitions in HTML for IDREF attributes w3c/aria#2474

Draft

alice and others added 5 commits March 14, 2025 16:20

Add notes an examples in the Element reference attributes section, an…

f8ad4a7

…d make some tweaks in the Reflection section

A few more minor tweaks

afbcf01

Remove stray edit

e350368

Simplify cases where 'reset the form owner' has to be called

b179371

Simplify cases where 'reset the form owner' has to be called

1d6c81e

Collapse most of the 'reset the form owner' checks into one that just watches for changes to the form(attr)-associated-element.

dandclark requested review from domenic and annevk March 18, 2025 00:17

Merge branch 'main' into dandclark/reference-target

7acf768

dandclark marked this pull request as ready for review March 18, 2025 00:30

rahimabdi mentioned this pull request Mar 23, 2025

Investigate changing ID-based WAI-ARIA value types due to referenceTarget w3c/aria#2487

Open

dandclark added 2 commits March 27, 2025 00:30

Fix a couple of cases where retargeting the form IDL attribute was mi…

19178ec

…ssed

Update return type from HTMLFormElement to HTMLElement for remaining …

cba0c5f

…IDL attributes

dandclark mentioned this pull request Mar 27, 2025

Reference Target: Should the form and list JavaScript attributes return the host element? WICG/webcomponents#1072

Closed

lukewarlow suggested changes Jul 31, 2025

View reviewed changes

source Outdated Show resolved Hide resolved

source Outdated Show resolved Hide resolved

source Outdated Show resolved Hide resolved

source Outdated Show resolved Hide resolved

source Outdated Show resolved Hide resolved

source Outdated Show resolved Hide resolved

dandclark added 4 commits August 6, 2025 20:57

Merge branch 'main' into dandclark/reference-target

f0b499c

Use [Reflect] syntax for HTMLTemplateElement.shadowRootReferenceTarget

518b2fa

Fix serialization of shadow root in HTML fragment serialization algor…

11532f5

…ithm

Fix linter issue for directly nested <ol>s

ccaf3e5

dandclark requested a review from lukewarlow August 6, 2025 21:37

lukewarlow requested review from lukewarlow and removed request for lukewarlow August 6, 2025 21:41

keithamus suggested changes Aug 28, 2025

View reviewed changes

smaug---- reviewed Sep 1, 2025

View reviewed changes

lukewarlow reviewed Sep 1, 2025

View reviewed changes

smaug---- reviewed Sep 1, 2025

View reviewed changes


		<li><p>If no such element exists, return null.</p></li>

		<li><p>Return the result of <span data-x="resolve-the-reference-target">resolving the reference

		readonly attribute <span>HTMLFormElement</span>? <span data-x="dom-label-form">form</span>;
		readonly attribute <span>HTMLElement</span>? <span data-x="dom-label-form">form</span>;

	<var>reflectedTarget</var>'s <span>explicitly set <var>attr</var>-elements</span>:</p>
	<var>element</var>'s <span>explicitly set <var>attr</var>-elements</span>:</p>

	<p>If <var>element</var>'s has an <span>explicitly set <var>attr</var>-elements</span> which
	<p>If <var>element</var> has an <span>explicitly set <var>attr</var>-elements</span> which

Add reference target #10995

Are you sure you want to change the base?

Add reference target #10995

Uh oh!

Conversation

dandclark commented Feb 5, 2025 • edited by pr-preview bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dandclark commented Mar 18, 2025

Uh oh!

alice commented Mar 19, 2025

Uh oh!

lukewarlow left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dandclark commented Aug 6, 2025

Uh oh!

lukewarlow commented Aug 6, 2025

Uh oh!

keithamus left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment was marked as resolved.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

dandclark commented Feb 5, 2025 •

edited by pr-preview bot

Loading