Add reference target by dandclark · Pull Request #10995 · whatwg/html

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 )

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.

lukewarlow

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

source

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.

As we discussed elsewhere, the reasoning here is:

This logic is just about how to actually make use of the reference target. (Probably this comment was actually meant to go somewhere else.)

We always resolve the reference target, even if we're just going to retarget the resulting value, so that we can handle invalid references by returning null.

We did explore the possibility in our discussion just now of not handling invalid references that way, and instead just not resolving the reference target for IDL attribute getters (in fact, this is what the original design did before that issue was filed), but my argument for keeping this behaviour was:

This is consistent with label.control for <label> wrapped: if no descendant element is labelable, either by being labelable itself or by having a labelable resolved reference target, label.control will return null. If there is a descendant element which has a labelable resolved reference target, that element will be returned.

This is also consistent with IDL setter/getters without reference target: if you attempt to set an invalid (e.g. in shadow DOM) element as an IDL attribute, for example lightDomElement.ariaActiveDescendantElement = shadowDomElement, the getter will return null (lightDomElement.ariaActiveDescendantElement === null).

I'm not convinced we actually gain that much either in code maintainability or in runtime performance in practice from skipping the resolve the reference target step for IDL attribute getters, since I think calls of these algorithms will be heavily dominated by "internal" callers which must do the resolution.

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?

referenceTargetValue?

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>

It seems this comment is still applicable. Though note that the second suggestion is wrong as it mixes candidate and element.

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?

I guess because there are two ways to collate candidates, and I didn't want to have each path also do the resolution.

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.

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 think main reason to have "get the attr-associated element(s)" do the retargeting is that we resolved that reference target should apply to all IDREF-type attributes: WICG/webcomponents#1091

So, when defining an attribute, the spec need only refer to "get the attr-associated element(s)" and it'll automatically be opted in to that behaviour, as well as automatically working with "explicitly-set attr-elements" iff the appropriate IDL attribute is defined.

If some attribute really wants to opt out, the spec can instead use the "first element whose ID matches" language (although there's not really a way to opt out and have the IDL attribute work).

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.

I think retargeting should work, regardless of whether this is in the same tree as candidate or in (relative) shadow DOM.

We did discuss a potential optimisation here: "get the attr-associated element" could take an optional argument, something like "encapsulation preserving" or "for bindings", which would cause the algorithm to return the non-resolved element iff resolving the element didn't return null. I'd be happy to draft a change to see what that would look like.

Ok, the latest change explores moving the "retargeting" step into the "get the attr-associated element(s)" algorithms (and not actually invoking retargeting, but instead just returning the shadow host we already found before resolving the reference target).

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

That's right. I'm not really sure of a clearer way to put it.

I wonder if this all works well for the Developer Edition of the standard as now we're phrasing conformance requirements in terms of algorithms aimed at implementers?

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?

Ah oops, I had intended to add that restriction and it must have dropped off my radar somewhere. Should be fixed now.

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.

Huh, yeah, something went weird there. Fixed.

source

alice

I had to apply all the code suggestions manually, because I foolishly pushed my changes before I'd applied them.

alice · 2025-09-08T14:31:26Z

source

+    </ol>
+   </li>
+
+   <li>If candidate is null, return null.</li>


Suggested change

<li>If candidate is null, return null.</li>

<li>If candidate is null, return null.</li>

alice · 2025-10-02T09:23:53Z

source

-      </ul>
-
-      <p>If no such element exists, then return null.</p>
+     <li><p>Let <var>candidate</var> be the result of running <span>this</span>'s


@dandclark @keithamus I filed WICG/webcomponents#1114 after having second thoughts about this logic.

annevk · 2025-10-10T14:19:15Z

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.</p>


Elements should be lowercase (applies multiple times!), unless you specifically want to talk about Element nodes/objects, but I don't think that's necessary here.

I fixed a couple here; I think that's all of them?

annevk · 2025-10-10T14:19:26Z

source

+
+  <ol>
+   <li><p>If <var>element</var> does not have a <span>shadow root</span>, or <var>element</var>'s
+   <span>shadow root</span>'s <span>reference target</span> is null, return <var>element</var>.</p>


then return*

annevk · 2025-10-10T14:20:32Z

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>


It seems this comment is still applicable. Though note that the second suggestion is wrong as it mixes candidate and element.

annevk · 2025-10-10T14:23:14Z

source

+   </p></li>
+  </ol>
+
+  <h5>Single element references</h5>


It should probably be "Single-element references" throughout (hyphen).

annevk · 2025-10-10T14:26:09Z

source

+  target</dfn> on an element <var>element</var> are:</p>
+
+  <ol>
+   <li><p>If <var>element</var> does not have a <span>shadow root</span>, or <var>element</var>'s


I don't understand what this means. Did you mean to say "If element is not a shadow host"?

Most likely, yes. Changed it to that.

annevk · 2025-10-10T14:30:00Z

source

-  <code>Element</code>, then with <var>attr</var> being the <span>reflected content attribute
-  name</span>:</p>
+  <p>If a <span>reflected IDL attribute</span> has the type <code>Element</code>, then with
+  <var>attr</var> being the <span>reflected content attribute name</span>:</p>


Why did you make this change? This seems wrong. And if this is somehow correct, let's make this change in a separate PR as it's unrelated.

I think this was because we realised that we couldn't really have the reflected elements be a specific type, since reference target means the attr-associated element might be in a shadow root and the shadow-host would be the reflected element.

To restate this (for my own edification, so if you could please confirm):

Prior to this change an IDL reflected attribute could be T because it could sub-type an element type, e.g. HTMLLabelElement would be a viable reflection. However as now we're using referencetarget, we need to retarget (or otherwise remap) that element to the host, therefore nothing can ever reflect T because it we can never guarantee it's the subtype as there's always a possibility that it's a host element.

I wonder if other specs (e.g. DOM? CSS?) implicitly rely on this reflection mechanism?

@keithamus That's exactly right.

As far as I know, nothing actually used this subtyping mechanism.

the ARIAMixin attributes which use this type of reflection are all Element or FrozenArray<Element>

popoverTargetElement is an Element?

commandForElement is an Element?

I think we had some idea that it might be useful for something like the form or headers attributes, which actually are limited to one specific element class, but a very limited and hypothetical benefit - even <label for>, which is limited to labelable elements, can't be limited by element class in this way.

To illustrate this with a code example (because it does confuse me too):

<fancy-form id="form"> <template shadowRootMode="open" shadowRootReferenceTarget="real-form"> <form id="real-form"></form> </template> </fancy-form> <input id="input">

// if we reflected `form` as an element attribute: input.formElement = document.getElementById("form");

This would be a working association, even though <fancy-form> doesn't inherit from HTMLFormElement, because the resolved reference target is the enclosed <form>.

annevk · 2025-10-10T14:31:14Z

source

+  data-x="">FrozenArray&lt;Element&gt;?</code>, then with <var>attr</var> being the <span>reflected
+  content attribute name</span>:</p>


Again this seems out-of-scope for this PR.

As above. I'm happy to revert them if you don't agree with the logic, though.

annevk · 2025-10-10T14:33:36Z

source

+  to</span> a <span data-x="category-label">labelable element</span>.</p>

-  <div w-nodev>
+  <p>To determine a <code>label</code> element's <dfn>labeled control</dfn>, run these steps:</p>


Suggested change

To determine a <code>label</code> element's <dfn>labeled control</dfn>, run these steps:

To determine a <code>label</code> element <var>label</var>'s <dfn>labeled control</dfn>:

(this also requires changes to the algorithm)

annevk · 2025-10-10T14:37:31Z

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>


I wonder if this all works well for the Developer Edition of the standard as now we're phrasing conformance requirements in terms of algorithms aimed at implementers?

annevk · 2025-10-10T14:39:44Z

source

       "<code data-x=""> shadowrootcustomelementregistry=&quot;&quot;</code>".</p></li>

+       <li>
+        <p>If <var>shadow</var>'s <span>reference target</span> is set, then:</p>


Suggested change

If <var>shadow</var>'s reference target is set, then:

If <var>shadow</var>'s reference target is set:

Though probably this should be "is non-null"? Generally we don't do optional fields.

I changed it to "non-null", and removed the "then". I'm a bit confused on when an "if" needs a "then" and when it doesn't, though.

… to shadow creation

…roperty

…ibute concepts.

…d make some tweaks in the Reflection section

alice · 2026-01-26T08:41:29Z

My apologies for letting this sit for so long. I've addressed Anne's comments, I think.

keithamus

Couple small issues:

keithamus · 2026-01-26T10:34:44Z

source

     <li><dfn data-x="concept-document-type" data-x-href="https://dom.spec.whatwg.org/#concept-document-type">document type</dfn> concept</li>
     <li><dfn data-x="concept-DocumentFragment-host" data-x-href="https://dom.spec.whatwg.org/#concept-documentfragment-host">host</dfn> concept</li>
-     <li>The <dfn data-x-href="https://dom.spec.whatwg.org/#concept-shadow-root">shadow root</dfn> concept, and its <dfn data-x-href="https://dom.spec.whatwg.org/#shadowroot-delegates-focus">delegates focus</dfn>, <dfn data-x-href="https://dom.spec.whatwg.org/#shadowroot-available-to-element-internals">available to element internals</dfn>, <dfn data-x-href="https://dom.spec.whatwg.org/#shadowroot-clonable">clonable</dfn>, <dfn data-x="shadow-serializable" data-x-href="https://dom.spec.whatwg.org/#shadowroot-serializable">serializable</dfn>, <dfn data-x="shadow-root-custom-element-registry" data-x-href="https://dom.spec.whatwg.org/#shadowroot-custom-element-registry">custom element registry</dfn>, and <dfn data-x-href="https://dom.spec.whatwg.org/#shadowroot-keep-custom-element-registry-null">keep custom element registry null</dfn>.</li>
+     <li>The <dfn data-x-href="https://dom.spec.whatwg.org/#concept-shadow-root">shadow root</dfn> concept, and its <dfn data-x-href="https://dom.spec.whatwg.org/#shadowroot-delegates-focus">delegates focus</dfn>, <dfn data-x-href="https://dom.spec.whatwg.org/#shadowroot-available-to-element-internals">available to element internals</dfn>, <dfn data-x-href="https://dom.spec.whatwg.org/#shadowroot-clonable">clonable</dfn>, <dfn data-x="shadow-serializable" data-x-href="https://dom.spec.whatwg.org/#shadowroot-serializable">serializable</dfn>, <dfn data-x="shadow-root-custom-element-registry" data-x-href="https://dom.spec.whatwg.org/#shadowroot-custom-element-registry">custom element registry</dfn>, <dfn data-x-href="https://dom.spec.whatwg.org/#shadowroot-keep-custom-element-registry-null">keep custom element registry null</dfn>, and <dfn data-x-href="https://dom.spec.whatwg.org/#shadowroot-reference-target">reference target</dfn>.</li>


Formatting nit, this should be broken into several lines I think (despite this whole block not following formatting conventions, multiple dfns are broken out, see L3260 below.

keithamus · 2026-01-27T11:20:25Z

source

-   <var>pending</var>.</p></li>
+   <li><p>If <var>root</var> has an <code data-x="attr-itemref">itemref</code> attribute, set
+   <var>pending</var> to the <span data-x="get the attr-associated elements">
+   <code data-x="attr-tdth-headers">itemref</code>-associated elements</span>.</p></li>


Suggested change

<code data-x="attr-tdth-headers">itemref</code>-associated elements.</li>

<code data-x="attr-itemref">itemref</code>-associated elements.</li>

keithamus · 2026-01-27T11:25:41Z

source

+        <p>If <var>shadow</var>'s <span>reference target</span> is non-null:</p>
+
+        <ol>
+         <li><p>Append "<code data-x=""> shadowrootreferencetarget=&quot;</code>".</p></li>


The formatting here breaks the reference. Probably something like:

Suggested change

<li>Append "<code data-x=""> shadowrootreferencetarget="</code>".</li>

<li>Append "<code data-x="shadowrootreferencetarget"> shadowrootreferencetarget="</code>".</li>

…d attr target element(s) and unresolved attr target element(s)

alice · 2026-01-27T14:40:51Z

Based on discussion in WICG/webcomponents#1114, I wanted to go ahead and fix the reflected attribute values to use a shallower/more naive algorithm. Specifically, we shouldn't need to resolve the reference target at all for reflected attribute getters.

@keithamus suggested it might be good to have separate algorithms for getting the elements referred to by an attribute - one for the "shallow" values, and one for the "resolved" values - which calls into the former.

I thought that was a great idea, so I've now completely renamed what used to be called "(get the) attr-associated element(s)" to "(get the) resolved attr target element(s)", with "(get the) unresolved attr target element(s)" as the "shallow" algorithm both the former algorithm and the reflected attribute getter calls into.

It's annoying to rename attr-associated elements like this, since it's now a relatively long-standing concept from reflected element attributes and a lot of method names in browsers refer to it directly, but I like the new names because:

it connects directly with "reference target" - I've also referred to "target" in more places in the prose now, as well
it means "form-associated element" goes back to having a single meaning (before this change, there was also form-associated element, i.e. the element referred to by the form attribute - that would now be referred to as the resolved form target element).

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

rniwa mentioned this pull request Feb 14, 2025

Add support for referenceTarget. WebKit/WebKit#39742

Merged

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

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

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 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 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 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

source Show resolved Hide resolved

alice mentioned this pull request Sep 5, 2025

Reference Target for Cross-Root ARIA web-platform-tests/interop#1011

Closed

alice reviewed Sep 8, 2025

View reviewed changes

dandclark mentioned this pull request Sep 24, 2025

Add the referencetarget feature web-platform-dx/web-features#3376

Merged

Westbrook mentioned this pull request Sep 29, 2025

Reference Target for Cross-Root ARIA WebKit/standards-positions#356

Open

alice reviewed Oct 2, 2025

View reviewed changes

annevk reviewed Oct 10, 2025

View reviewed changes

TimvdLippe mentioned this pull request Nov 11, 2025

Implement referenceTarget servo/servo#40561

Open

dandclark and others added 18 commits January 23, 2026 16:30

Add shadowrootreferencetarget attribute to template, plumb it through…

c8212a1

… to shadow creation

Begin exploring how to specify what effect referenceTarget has.

816d5ec

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

84f27bb

…roperty

Implicit label association accounts for reference target

46ea969

Don't directly nest <ol>s

5e26497

Actually return the resolved reference target from labeled control algo

11bdbcc

Add a section about multiple element reference attributes

eb83376

Update HTMLLabelElement control and form properties

ddba466

Update the HTMLInputElement.list attribute

5288be0

Update headers property

33925e3

Update form association

513b4b6

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

7b1ef01

…ibute concepts.

Update output-for and popover, and reword definitions

1f4f82c

Update itemref attribute

39fdb29

Update attributes table

ede4026

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

c3b0cba

…d make some tweaks in the Reflection section

A few more minor tweaks

19f0f07

Address Anne's review comments

5d6f658

alice force-pushed the dandclark/reference-target branch from 397e6d6 to 5d6f658 Compare January 26, 2026 08:39

keithamus reviewed Jan 27, 2026

View reviewed changes

Split attr-associated elements into two different algorithms: resolve…

99765dc

…d attr target element(s) and unresolved attr target element(s)


		<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

	<li>If candidate is null, return null.</li>
	<li><p>If candidate is null, return null.</p></li>

		data-x="">FrozenArray<Element>?</code>, then with <var>attr</var> being the <span>reflected
		content attribute name</span>:</p>

	<p>To determine a <code>label</code> element's <dfn>labeled control</dfn>, run these steps:</p>
	<p>To determine a <code>label</code> element <var>label</var>'s <dfn>labeled control</dfn>:</p>

	<p>If <var>shadow</var>'s <span>reference target</span> is set, then:</p>
	<p>If <var>shadow</var>'s <span>reference target</span> is set:</p>

	<code data-x="attr-tdth-headers">itemref</code>-associated elements</span>.</p></li>
	<code data-x="attr-itemref">itemref</code>-associated elements</span>.</p></li>

	<li><p>Append "<code data-x=""> shadowrootreferencetarget="</code>".</p></li>
	<li><p>Append "<code data-x="shadowrootreferencetarget"> shadowrootreferencetarget="</code>".</p></li>

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!

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!

dandclark commented Feb 5, 2025 •

edited by pr-preview bot

Loading