Reference Target for Cross-root ARIA

at a glance

why it exists

Shadow DOM encapsulation breaks IDREF-based relationships. A component that wraps a native control — the explainer's examples are a design-system <sp-checkbox> enclosing a real <input type="checkbox">, and an <md-dialog> enclosing a real <dialog> with scrim and focus-trap markup — cannot be the target of a <label for>, an aria-labelledby, or a popovertarget in any useful way: the reference points at the host, not at the internal element that actually implements the behavior. Before Reference Target, component authors had to break encapsulation (hoist IDs, duplicate ARIA onto the host and mirror state) or leave assistive technology and label activation broken. Reference Target lets the host substitute an enclosed element for exactly those IDREF purposes, and nothing else.

how forwarding works

Setting a reference target is a declaration on the shadow root: the ID of one element in the shadow tree. From then on, when the host element is the target of an IDREF attribute, the reference resolves to the reference target instead of the host. The explainer defines the intended scope as all attributes that refer to another element by ID string:

References are live. The effective target is recomputed when any of the following changes (explainer, verbatim list):

• The host changes its referenceTarget to refer to a different ID.
• An element with an id matching the host's referenceTarget is added to or removed from the host's shadow tree.
• The id attribute of an element inside the host's shadow tree is changed to or from the referenceTarget ID.
• The host is added or removed from the DOM.
• The host's id attribute is changed.

declarative syntax

With declarative shadow DOM, the reference target is set with the shadowrootreferencetarget attribute on the <template> element — the value is the id of an element inside that template:

<label for="my-checkbox">Checkbox value (click me to toggle checkbox)</label>
<custom-checkbox id="my-checkbox">
  <template shadowrootmode="open" shadowrootreferencetarget="real-checkbox">
    <input id="real-checkbox" type="checkbox">
  </template>
</custom-checkbox>

The label's for="my-checkbox" points at the host, but activation, accessibility computation, and HTMLInputElement.labels all treat the enclosed <input id="real-checkbox"> as the labeled control. The same value can be read back via the HTMLTemplateElement.shadowRootReferenceTarget IDL reflection (on the JS surface page: ShadowRoot.referenceTarget & friends →).

interaction contracts and edge cases

relationship to ARIA Element reflection (aria-actions & friends)

Reference Target composes with — but does not replace — the ARIA Element-reflection family (ariaLabelledByElements, ariaControlsElements, and Chrome 151's ariaActionsElements). The two mechanisms answer different questions: Element reflection lets script assign target elements by reference instead of by ID string (and, per the interaction contract above, those getters return the host when forwarding is in play); Reference Target lets a component author decide where IDREFs that point at the host should land inside its shadow tree. A page can use both: el.ariaControlsElements = [fancyListboxHost] targets the host by reference, and the host's referenceTarget forwards the resulting AT relationship to the internal listbox.

examples

Imperative setup (the explainer's sp-checkbox, closed root):

class Checkbox extends HTMLElement {
  constructor() {
    super();
    const root = this.attachShadow({ mode: "closed", referenceTarget: "input" });
    root.innerHTML = `<input id="input" type="checkbox">`;
  }
}
customElements.define("sp-checkbox", Checkbox);

// <label for="consent"> + <sp-checkbox id="consent"> — the label now
// labels the internal input: click activation, accName, and input.labels all work.

The Chrome Platform Showcase feature page for Reference Target (HEAD-checked 200, 2026-07-28) hosts the interactive demos; there is no concept sub-route to embed yet, so this page links rather than iframes. The Microsoft Edge reference-target demo (from the ChromeStatus sample links) is a second live example.

browser compatibility

security and privacy

Reference Target preserves shadow encapsulation rather than weakening it: outside pages learn only that IDREFs to the host resolve to some internal element, not which one — Element-reflecting JavaScript getters (ariaControlsElements, HTMLLabelElement.control, …) return the host, never the internal target, so shadow-internal element references cannot leak out through script (see interaction contracts). CSS selectors and event retargeting are unaffected. No new storage, network, or fingerprinting surface is introduced in the sources read.

specifications

see also

• gendn — ShadowRoot.referenceTarget, ShadowRootInit.referenceTarget, and the template reflection (JS surface)
• gendn v151 — aria-actions (ARIA Element reflection family)
• gendn v151 — shadowrootslotassignment (sibling declarative-shadow-DOM attribute)
• blink-dev — Intent to Ship: Reference Target
• W3C TAG design review #961
• WICG/webcomponents #1091 — referenceTarget support for aria-owns
• Chromium tracking bug 346835896
• Chrome Platform Showcase — this feature · Microsoft Edge demo