ShadowRoot.mode — Eigenschaft · JavaScript-Referenz

Signatur

ShadowRoot.mode

Beschreibung

Die Eigenschaft ShadowRoot.mode gibt an, mit welchem Modus ein Shadow Root über Element.attachShadow({ mode }) oder deklarativ per <template shadowrootmode> erzeugt wurde. Der Wert wird bei der Erzeugung festgelegt und kann danach nicht mehr geändert werden.

"open": Von außen kann man über element.shadowRoot auf den Shadow Root zugreifen. JavaScript außerhalb der Komponente kann also den internen DOM-Baum lesen und ändern.
"closed": element.shadowRoot liefert null. Nur wer die von attachShadow() zurückgegebene Referenz aufbewahrt, kann auf den Baum zugreifen.

Nützlich ist mode vor allem in Bibliotheks- und Werkzeugcode, der beliebige Shadow Roots verarbeitet, z. B. beim Durchlaufen des DOM, in Test-Hilfsfunktionen oder beim Debuggen. So lässt sich prüfen, ob eine Komponente absichtlich abgeschottet wurde. Auch event.composedPath() berücksichtigt den Modus: Knoten innerhalb geschlossener Shadow Roots werden für Listener außerhalb ausgeblendet.

Rückgabewert

Typ

"open" | "closed"

Beschreibung

Ein String mit dem Modus, der beim Erzeugen des Shadow Root festgelegt wurde.

Beispiele

Modus eines offenen Shadow Root abfragen

const host = document.createElement('div');
const root = host.attachShadow({ mode: 'open' });

console.log(root.mode);               // Modus direkt am ShadowRoot
console.log(host.shadowRoot === root); // Von außen erreichbar

open true

Geschlossener Shadow Root in einer Web Component

class SecretBox extends HTMLElement {
  #root; // Referenz privat aufbewahren

  constructor() {
    super();
    this.#root = this.attachShadow({ mode: 'closed' });
    this.#root.innerHTML = '<p>Intern</p>';
  }

  get rootMode() {
    return this.#root.mode;
  }
}
customElements.define('secret-box', SecretBox);

const box = document.createElement('secret-box');
console.log(box.rootMode);   // Modus über interne Referenz
console.log(box.shadowRoot); // Von außen nicht zugänglich

closed null

Hilfsfunktion: Modus robust ermitteln

const getShadowInfo = (el) => {
  const root = el.shadowRoot;
  if (root) return `offen (${root.mode})`;
  // closed oder gar kein Shadow Root – von außen nicht unterscheidbar
  return 'kein Zugriff (closed oder nicht vorhanden)';
};

const a = document.createElement('div');
a.attachShadow({ mode: 'open' });
const b = document.createElement('div');
b.attachShadow({ mode: 'closed' });

console.log(getShadowInfo(a));
console.log(getShadowInfo(b));

offen (open) kein Zugriff (closed oder nicht vorhanden)

Deklarativer Shadow DOM

// HTML: <div id="card"><template shadowrootmode="open"><slot></slot></template></div>
const card = document.getElementById('card');
console.log(card.shadowRoot?.mode ?? 'kein offener Shadow Root');

open

// Wichtig · Fallstricke

Schreibgeschützt: Wenn man root.mode = 'closed' zuweist, wird das ignoriert, im Strict Mode gibt es einen TypeError. Der Modus steht nach der Erzeugung fest.
"closed" ist kein Sicherheitsmechanismus. Fremde Skripte auf derselben Seite können zum Beispiel Element.prototype.attachShadow vorher überschreiben und so die Referenz abgreifen. Sensible Daten oder Schutz vor XSS gehören nicht in einen geschlossenen Shadow Root.
Von außen lässt sich "closed" nicht von „kein Shadow Root“ unterscheiden, denn in beiden Fällen ist element.shadowRoot null.
Geschlossene Shadow Roots erschweren Tests, Barrierefreiheits-Werkzeuge und Browser-Erweiterungen. Für die meisten Komponenten wird "open" empfohlen.
ElementInternals.shadowRoot gibt einer Custom-Element-Klasse auch bei "closed" Zugriff auf den eigenen Shadow Root.
Kompatibilität: Die Eigenschaft wird in allen aktuellen Browsern unterstützt (Chrome/Edge 53+, Firefox 63+, Safari 10.1+). Das deklarative Attribut shadowrootmode ist erst seit 2024 Baseline.

Siehe auch

ShadowRoot Element.attachShadow() Element.shadowRoot ShadowRoot.host ShadowRoot.delegatesFocus Event.composedPath() RTCStatsReport.size