ShadowRoot.delegatesFocus — Eigenschaft · JavaScript-Referenz

Signatur

ShadowRoot.delegatesFocus

Beschreibung

Die Eigenschaft delegatesFocus spiegelt die Option wider, mit der ein Shadow Root über Element.attachShadow({ mode, delegatesFocus }) oder deklarativ per <template shadowrootmode="open" shadowrootdelegatesfocus> erzeugt wurde. Einmal festgelegt, lässt sich der Wert nicht mehr ändern.

Ist die Delegation aktiv, bekommt beim Fokussieren des Host-Elements (per Klick auf einen nicht fokussierbaren Bereich, durch host.focus() oder Tab-Navigation) automatisch das erste fokussierbare Element im Shadow DOM den Fokus. Außerdem trifft die CSS-Pseudoklasse :focus auf den Host zu, sobald ein Element in seinem Shadow Tree fokussiert ist. So verhält sich eine Web Component wie ein natives Formularelement.

Man verwendet die Eigenschaft vor allem, um in Bibliotheken, Tests oder Debugging-Code zu prüfen, wie eine Komponente konfiguriert wurde, etwa um Fokus-Styles oder die Tastaturbedienbarkeit korrekt zu behandeln.

Beispiele

Shadow Root mit Fokus-Delegation anlegen und prüfen

const host = document.createElement('div');
document.body.append(host);

const shadow = host.attachShadow({ mode: 'open', delegatesFocus: true });
shadow.innerHTML = `<span>Name:</span> <input type="text">`;

console.log(shadow.delegatesFocus);

// Host fokussieren: Fokus landet im <input>
host.focus();
console.log(shadow.activeElement?.tagName);

true INPUT

Standardwert ohne Option

const host = document.createElement('section');
const shadow = host.attachShadow({ mode: 'open' });
console.log(shadow.delegatesFocus);

false

Custom Element wie ein natives Eingabefeld

class FancyInput extends HTMLElement {
  constructor() {
    super();
    const root = this.attachShadow({ mode: 'open', delegatesFocus: true });
    root.innerHTML = `
      <style>
        :host(:focus) { outline: 2px solid royalblue; }
      </style>
      <label>Suche <input type="search"></label>`;
  }

  get delegiertFokus() {
    return this.shadowRoot.delegatesFocus;
  }
}

customElements.define('fancy-input', FancyInput);
const el = document.createElement('fancy-input');
document.body.append(el);
console.log(el.delegiertFokus);

true

Deklaratives Shadow DOM auswerten

document.body.setHTMLUnsafe(`
  <my-field>
    <template shadowrootmode="open" shadowrootdelegatesfocus>
      <input>
    </template>
  </my-field>`);

const root = document.querySelector('my-field').shadowRoot;
console.log(root.delegatesFocus);

true

// Wichtig · Fallstricke

Schreibgeschützt: Zuweisungen wie shadow.delegatesFocus = true bleiben wirkungslos (im Strict Mode TypeError). Der Wert kann nur beim Erzeugen per attachShadow() bzw. über das Attribut shadowrootdelegatesfocus gesetzt werden.
Bei mode: 'closed' liefert host.shadowRoot null. Dann kommt man nur über die von attachShadow() zurückgegebene Referenz an die Eigenschaft.
:focus trifft bei Delegation auch auf den Host zu. Das kann zu doppelten Fokusrahmen führen. Besser gezielt mit :host(:focus-within) oder :focus-visible stylen.
Gibt es im Shadow Tree kein fokussierbares Element, bekommt beim Fokussieren des Hosts nichts den Fokus.
Kompatibilität: Firefox unterstützt die Eigenschaft erst ab Version 94, Safari ab 15. Deklaratives Shadow DOM mit shadowrootdelegatesfocus gibt es erst seit 2024 in allen großen Browsern.

Siehe auch

ShadowRoot.customElementRegistry ShadowRoot.styleSheets ShadowRoot.adoptedStyleSheets ShadowRoot.clonable ShadowRoot.innerHTML