Element.customElementRegistry — Eigenschaft · JavaScript-Referenz

Signatur

get Element.customElementRegistry

Beschreibung

Die schreibgeschützte Eigenschaft customElementRegistry zeigt, über welche CustomElementRegistry ein Element seine Custom-Element-Definition bezieht. Sie gehört zur Erweiterung Scoped Custom Element Registries. Damit hat eine Seite nicht mehr zwingend nur eine globale Registry (window.customElements), sondern es kann mehrere, voneinander getrennte Registries geben – zum Beispiel eine eigene pro Shadow Root.

Ein Element bekommt seine Registry beim Erzeugen. Normale Elemente im Hauptdokument nutzen die globale Registry. Elemente in einer Shadow Root, die mit attachShadow({ customElementRegistry }) angelegt wurde, nutzen die dort angegebene Registry. Mit document.createElement(name, { customElementRegistry }) kann man die Registry auch direkt festlegen. Hat ein Element keine Registry, etwa in Dokumenten aus DOMParser oder im Inhalt eines <template>, ist der Wert null.

Die Eigenschaft hilft vor allem in Bibliotheken und Micro-Frontends. Dort können mehrere Komponenten-Versionen denselben Tag-Namen verwenden, ohne sich in die Quere zu kommen. Mit customElementRegistry lässt sich zur Laufzeit prüfen, welche Definition für ein Element gilt, zum Beispiel über el.customElementRegistry.get(el.localName).

Rückgabewert

Typ

CustomElementRegistry | null

Beschreibung

Die dem Element zugeordnete Registry oder null, wenn es keine gibt. Die Eigenschaft ist schreibgeschützt: Wenn man ihr etwas zuweist, passiert nichts (im Strict Mode wird ein TypeError ausgelöst).

Beispiele

Standardfall: globale Registry

const div = document.createElement('div');
console.log(div.customElementRegistry === window.customElements);

true

Eigene Registry für eine Shadow Root

class FancyButton extends HTMLElement {
  connectedCallback() {
    this.textContent = 'Lokaler Button';
  }
}

// Eigene Registry anlegen und das Element nur dort registrieren
const registry = new CustomElementRegistry();
registry.define('fancy-button', FancyButton);

const host = document.createElement('div');
document.body.append(host);
const shadow = host.attachShadow({ mode: 'open', customElementRegistry: registry });
shadow.innerHTML = '<fancy-button></fancy-button>';

const btn = shadow.querySelector('fancy-button');
console.log(btn.customElementRegistry === registry);          // true
console.log(btn.customElementRegistry.get('fancy-button') === FancyButton); // true
console.log(customElements.get('fancy-button'));             // undefined (nicht global)

true true undefined

Registry beim Erzeugen festlegen und null-Fall

const registry = new CustomElementRegistry();
registry.define('info-card', class extends HTMLElement {});

const card = document.createElement('info-card', { customElementRegistry: registry });
console.log(card.customElementRegistry === registry);

// Dokumente ohne Browsing-Kontext haben keine Registry
const parsed = new DOMParser().parseFromString('<p>Hallo</p>', 'text/html');
console.log(parsed.querySelector('p').customElementRegistry);

true null

Unterstützung prüfen

const supportsScoped = 'customElementRegistry' in Element.prototype;

const getDefinition = (el) =>
  supportsScoped
    ? el.customElementRegistry?.get(el.localName)
    : customElements.get(el.localName);

console.log(supportsScoped ? 'Scoped Registries verfügbar' : 'Nur globale Registry');

Scoped Registries verfügbar

// Wichtig · Fallstricke

Browser-Unterstützung: Scoped Custom Element Registries sind neu (Safari 26, neuere Chromium-Versionen). Die Eigenschaft ist noch nicht Baseline. Vorher per 'customElementRegistry' in Element.prototype prüfen; für ältere Browser gibt es einen Polyfill (@webcomponents/scoped-custom-element-registry).
Ist der Wert null, muss das nicht bedeuten, dass das Element kein Custom Element ist. Oft wurde es nur in einem Dokument ohne Registry erzeugt (DOMParser, <template>-Inhalt, document.implementation.createHTMLDocument()). Deshalb vor dem Zugriff mit ?. absichern.
Wird eine Shadow Root mit customElementRegistry: null angelegt, hat sie zunächst keine Registry. Mit registry.initialize(shadowRoot) kann man ihr später eine zuweisen.
Ein bereits erzeugtes Element behält seine Registry, auch wenn man es in einen anderen Baum verschiebt. Nur Elemente ohne Registry können nachträglich eine bekommen.
Die Eigenschaft ist schreibgeschützt. Die Registry kann man nur beim Erzeugen festlegen oder über initialize(), nicht durch eine Zuweisung.

Siehe auch

Element.lastElementChild Element.childElementCount Element.firstElementChild Element.elementTiming Element.nextElementSibling