ShadowRoot.referenceTarget

syntax

Verbatim from Chromium's shadow_root.idl (the comment is part of the source):

// The referenceTarget attribute is the ID of an element in the shadow tree.
// When the host element is the target of an IDREF attribute like
// aria-activedescendant, the reference resolves to the referenceTarget.
// See https://crbug.com/346835896
[RuntimeEnabled=ShadowRootReferenceTarget] attribute DOMString? referenceTarget;

The ShadowRootInit dictionary member, verbatim from shadow_root_init.idl:

dictionary ShadowRootInit {
  required ShadowRootMode mode;
  boolean delegatesFocus;
  SlotAssignmentMode slotAssignment;
  [RuntimeEnabled=ScopedCustomElementRegistry] CustomElementRegistry? customElementRegistry;
  boolean serializable;
  boolean clonable;
  [RuntimeEnabled=ShadowRootReferenceTarget] DOMString? referenceTarget;
  // Note: if you add a parameter here, be sure to add it to the list of checks
  // in Element::attachShadow() for existing declarative shadow roots.
};

And the declarative-shadow-DOM reflection, verbatim from html_template_element.idl:

[CEReactions, Reflect, RuntimeEnabled=ShadowRootReferenceTarget]
attribute DOMString? shadowRootReferenceTarget;

inputs (setting)

outputs (getting)

The getter returns the current value as a DOMString? — the ID string last set (via IDL, ShadowRootInit, or the declarative attribute), or null when no reference target is set. It returns the ID string, not the element: resolving the string to an element is the engine's job at IDREF-lookup time; script that wants the element does its own shadowRoot.getElementById(value). On a closed root the property exists on the ShadowRoot object but is only reachable where script retained a reference to that root — it does not leak through the host.

errors and edge cases

context and exposure

ShadowRoot.referenceTarget and the ShadowRootInit member are exposed in Window (the interface is [Exposed=Window]) and gated by the ShadowRootReferenceTarget runtime feature (status: "stable" at trunk; origin_trial_feature_name: "ShadowRootReferenceTarget" for the concluded 133–135 origin trial). The template reflection is likewise [RuntimeEnabled=ShadowRootReferenceTarget]. Feature-detect:

const supported = "referenceTarget" in ShadowRoot.prototype;

lifecycle and live updates

The reference target is a live reference: the engine re-resolves it whenever the relevant state changes. From the explainer (verbatim list):

• The host changes its referenceTarget to refer to a different ID.
• An element with an id that matches its 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 roots serialize the setting: getHTML({ serializableShadowRoots: true }) emits shadowrootreferencetarget (WPT gethtml-serialization.html), and the dictionary comment in shadow_root_init.idl records that new ShadowRootInit members join the existing-declarative-root equality checks in Element::attachShadow() — an imperative re-attach over a declarative root must match the declarative referenceTarget value.

examples

// Set at creation (open or closed root):
const root = host.attachShadow({ mode: "open", referenceTarget: "real-input" });
root.innerHTML = `<input id="real-input">`;

// Or later, via the IDL attribute:
root.referenceTarget = "other-input";

// Read back — an ID string or null:
console.log(root.referenceTarget);           // "other-input"
console.log(root.getElementById(root.referenceTarget)); // the element

// Declarative equivalent + reflection:
// <template shadowrootmode="open" shadowrootreferencetarget="real-checkbox">…</template>
console.log(templateEl.shadowRootReferenceTarget); // "real-checkbox"

Live-update behavior (from the explainer's guarantee): after root.referenceTarget = "other-input", an existing <label for="host-id"> immediately labels #other-input — no observer or re-registration needed.

compatibility

BCD marks both entries experimental: true and does not yet record Chrome 152's default-on (checked 2026-07-28 — freshness gap; the milestone listing is authoritative for Chrome).

security and privacy

Reference Target is designed to preserve shadow encapsulation rather than weaken it: the only new information an outside page gains is that IDREFs to the host resolve to some internal element — the internal structure (which ID, what markup) is not exposed. Element-reflecting JavaScript getters deliberately return the host, never the internal target (interaction contract), so script cannot launder shadow-internal element references out through ariaControlsElements or HTMLLabelElement.control. CSS selectors and event retargeting are unaffected (WPT event-path.html). No new storage, network, or fingerprinting surface is introduced in the sources read.

see also

• gendn — Reference Target for Cross-root ARIA (overview: mechanism, supported attributes, interactions)
• Chromium shadow_root.idl · shadow_root_init.idl · html_template_element.idl
• whatwg/dom PR #1353 (ShadowRoot-side normative change, OPEN) · whatwg/html PR #10995 (OPEN)
• WPT shadow-dom/reference-target/tentative/: WPT shadowrootreferencetarget-idl-reflection.html · property-reflection.html
• chromestatus.com/feature/5188237101891584