Add reference target to shadow root by dandclark · Pull Request #1353 · whatwg/dom

dandclark · 2025-02-04T21:02:41Z

Reference Target is a feature to enable using 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. The main goal of this feature is to enable ARIA to work across shadow root boundaries.

In this change, add the referenceTarget property to ShadowRoot and add a definition of reference target that's exported for use in other specs.

See the reference target explainer.

At least two implementers are interested (and none opposed):
- Chromium is positive (I'd like to ship it there)
- Reference Target for Cross-Root ARIA mozilla/standards-positions#1035 (Positive)
- 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
- 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
MDN issue is filed: Create documentation for Reference Target mdn/mdn#832
The top of this comment includes a clear commit message to use.

Preview | Diff

- Add the concept of a "source" for an Event. - Modify shadow root's "get the parent" algorithm such that events propagate into the event's source's tree where appropriate.

…e-target

dandclark · 2026-05-19T21:02:21Z

@annevk , @smaug---- , this is ready for another review along with whatwg/html#10995. For context on the event propagation change, see WICG/webcomponents#1098. Thanks!

smaug---- · 2026-05-19T21:23:42Z

What is the current testing situation? alice added several tests, but this is a rather complicated feature (at least from implementation point of view) so we need to ensure testing coverage is particularly good.
Gecko doesn't fail currently in too many (when run in Mozilla CI).
Chrome fails only some on wpt.fyi.

But are we testing all the complicated cases?

dandclark · 2026-05-19T21:48:39Z

I've tried to ensure that the WPTs for this are thorough; I and other contributors added quite a few during work on the Chromium prototype.

E.g. https://wpt.fyi/results/shadow-dom/reference-target/tentative/property-reflection.html and https://wpt.fyi/results/shadow-dom/reference-target/tentative/property-reflection-idl-setters.html test reflection behavior for all the properties affected by reference target, with references pointing to and from every HTML element type.

https://github.com/web-platform-tests/wpt/blob/master/shadow-dom/reference-target/tentative/event-path.html covers all the interesting event propagation scenarios discussed in WICG/webcomponents#1098, plus some others I thought of.

All of the platform features testable in WPTs that can be affected by reference target (form submission, commandfor, interestfor, <label> (implicit association and with for)), popovertarget, and aria-labelledby, have WPTs under https://wpt.fyi/results/shadow-dom/reference-target/tentative.

There are a few other ARIA properties affected by reference target that aren't yet testable in WPTs; there are tests for those in the Chromium source tree at https://source.chromium.org/chromium/chromium/src/+/main:third_party/blink/web_tests/shadow-dom/reference-target/tentative/.

For some reason it doesn't seem like the Mozilla CI results are including the full set of tests. There are a larger number of tests in https://wpt.fyi/results/shadow-dom/reference-target/tentative that Gecko is shown as failing that don't appear in the linked Mozilla CI results.

smaug---- · 2026-05-19T22:48:18Z

The pref in Gecko isn't enabled in Nightly, so wpt.fyi still shows many tests as failing. The pref is enabled in Mozilla CI.

annevk · 2026-05-20T14:46:28Z

+<ol>
+ <li><p>If <var>event</var>’s <a>composed flag</a> is set, return <a for=/>shadow root</a>’s
+ <a for=DocumentFragment>host</a>.</p></li>
+ <li><p>Let <var>target</var> be <var>event</var>’s <a for=Event>path</a>'s first struct's


Can we use path[0] here?

annevk · 2026-05-20T15:09:11Z

+ <var>source</var>, return <a for=/>shadow root</a>'s <a for=DocumentFragment>host</a>.</p></li>
+ <li><p>If <var>source</var> is not null, and <var>source</var>'s <a for=tree>root</a> is a
+ <a>shadow-including ancestor</a> of <a for=/>shadow root</a>, return the result of
+ <a>retargeting</a> <var>target</var> against <var>source</var>.</p></li>


I wonder if we should add one or two examples here because this is getting rather involved. It seems really weird that as part of calculating the dispatch tree we are retargeting.

Also just to return the event target as the parent of the shadow tree. I can't really wrap my head around this.

This in particular I would expect to have test coverage for every branch in detail. Including capture and bubble phases, the works. Does that exist?

annevk · 2026-05-20T16:50:44Z

 <code>relatedTarget</code> attribute. [[UIEVENTS]]

+<p>An <a>event</a> has an associated <dfn export for=Event>source</dfn> (a
+<a>potential event target</a>). Unless stated otherwise it is null.


This should probably have a note explaining where this is used. "Other specifications ..."

smaug---- · 2026-05-28T14:07:15Z

+
+ <li><p>If <var>source</var> is not null, and <var>source</var>'s <a for=tree>root</a> is a
+ <a>shadow-including ancestor</a> of <var>shadowRoot</var>, then return the result of
+ <a>retargeting</a> <var>target</var> against <var>source</var>.


As I said in WICG/webcomponents#1098 (comment) I think we should still investigate relatedTarget model for this. Basically, the relevant events would be composed but propagate only up to the level where .target and .source are different.

Add reference target to shadow root

e06f903

rniwa mentioned this pull request Feb 14, 2025

Add support for referenceTarget. WebKit/WebKit#39742

Merged

This was referenced Mar 7, 2025

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

Draft

Add reference target whatwg/html#10995

Open

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

smaug---- reviewed Mar 18, 2025

View reviewed changes

Comment thread dom.bs

annevk reviewed Apr 7, 2025

View reviewed changes

Comment thread dom.bs Outdated

Comment thread dom.bs

dandclark and others added 4 commits May 6, 2025 23:12

Merge branch 'main' into dandclark/reference-target

9ce89ff

Make order consistent with other ShadowRoot properties

496ccae

Add type declaration for ShadowRoot reference target

64676d6

Propagate events into the event's source's tree where appropriate.

ec59294

- Add the concept of a "source" for an Event. - Modify shadow root's "get the parent" algorithm such that events propagate into the event's source's tree where appropriate.

alice mentioned this pull request Sep 5, 2025

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

Closed

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

annevk reviewed Oct 10, 2025

View reviewed changes

Comment thread dom.bs

github-actions Bot mentioned this pull request Nov 25, 2025

Reference target web-platform-dx/developer-signals#446

Open

dandclark added 2 commits January 29, 2026 14:58

Merge remote-tracking branch 'origin' into dandclark/reference-target

94f706b

Add missing definition for ShadowRoot.referenceTarget getter/setter

9a82ae0

hamishwillee mentioned this pull request Mar 16, 2026

[Web API] Add referenceTarget and shadowRootReferenceTarget attributes mdn/content#43453

Open

8 tasks

Merge branch 'alice-event-source-propagation' into dandclark/referenc…

d31bf7d

…e-target

This was referenced May 19, 2026

[DRAFT] Propagate events into the event's source's tree where appropriate. #1377

Draft

Create documentation for Reference Target mdn/mdn#832

Open

dandclark mentioned this pull request May 19, 2026

Reference Target whatwg/html#10707

Open

annevk reviewed May 20, 2026

View reviewed changes

dandclark added 3 commits May 26, 2026 14:53

Merge branch 'main' into dandclark/reference-target

bb4d558

Misc style/formatting/typo fixups

c6fbd2c

Remove one more closing </p>

6f1bbe2

github-actions Bot mentioned this pull request May 27, 2026

Reference target web-platform-dx/developer-signals#833

Open

smaug---- reviewed May 28, 2026

View reviewed changes

Conversation

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

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dandclark commented May 19, 2026

Uh oh!

smaug---- commented May 19, 2026

Uh oh!

dandclark commented May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

smaug---- commented May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

annevk May 20, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

annevk May 20, 2026

Choose a reason for hiding this comment

Uh oh!

annevk May 20, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

annevk May 20, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

smaug---- May 28, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

4 participants

dandclark commented Feb 4, 2025 •

edited by pr-preview Bot

Loading

dandclark commented May 19, 2026 •

edited

Loading

smaug---- commented May 19, 2026 •

edited

Loading