Zorg ervoor dat aangepaste elementen zich gedragen met bereikgebonden registers.

Jayson Chen

Patrick Brosset

Gepubliceerd: 9 maart 2026

Met aangepaste elementen kunnen ontwikkelaars van webapplicaties UI-componenten met hun unieke gedrag bouwen, delen en hergebruiken, waardoor de ontwikkeling eenvoudiger wordt. Maar wanneer uw app verschillende sets aangepaste elementen combineert, kan het onoverzichtelijk worden en kunnen er naamconflicten ontstaan. Scoped custom element registries bieden hiervoor de oplossing!

Het Microsoft Edge-team heeft aan deze functie gewerkt en we zijn verheugd aan te kondigen dat scoped custom element registries nu standaard beschikbaar zijn in Edge en Chrome 146, evenals in andere op Chromium gebaseerde browsers. Je kunt nu custom elements inkapselen, waarmee een al lang bestaand probleem voor ontwikkelaars van componenten en micro-frontendbibliotheken wordt opgelost.

Met scoped custom element registries worden belangrijke patronen voor webontwikkelaars toegankelijk. Nu kunt u meerdere custom element libraries gebruiken, onafhankelijk ontwikkeld door verschillende teams, of meerdere versies van dezelfde library naast elkaar.

Wat is een scoped custom element registry?

Momenteel bevindt elke definitie van een aangepast element op een webpagina zich in één gedeeld register op window.customElements . Dit betekent dat als twee verschillende bibliotheken proberen een aangepast element met dezelfde tagnaam te definiëren, zoals <my-button> , er een foutmelding wordt gegenereerd en de pagina niet meer werkt. Dit is een significant probleem in de praktijk. Grote applicaties waarvan de gebruikersinterfaces door meerdere teams, ontwerpsystemen of micro-frontends worden samengesteld, kunnen gemakkelijk te maken krijgen met naamconflicten. Scoped custom element registries lossen dit op door het mogelijk te maken onafhankelijke registers te creëren. Elk register beheert zijn eigen set definities van aangepaste elementen, volledig geïsoleerd van het globale register en van elkaar.

Een nieuw register aanmaken

In plaats van elk aangepast element in het globale window.customElements -register te definiëren:

1. Maak een nieuw register aan door de functie new CustomElementRegistry() aan te roepen.
2. Geef uw nieuwe register een specifiek bereik (zie Het bereik van uw register instellen).
3. Definieer de elementen die in het nieuwe register worden opgenomen.

Wanneer een aangepast element wordt gebruikt, zoekt de browser de definitie van het element op in het bijbehorende register, wat niet per se het globale register hoeft te zijn. Dit betekent dat verschillende delen van uw pagina volledig verschillende sets definities van aangepaste elementen kunnen gebruiken.

Omvang van uw register

Een aangepast elementenregister kan worden gekoppeld aan een document, een schaduwhoofdmap of een individueel element.

Bereik naar een schaduwroot

Om een ​​nieuw register te koppelen aan een shadow root, gebruikt u de optie customElementRegistry bij het aanroepen van de attachShadow() methode. Alle aangepaste elementen binnen die shadow root gebruiken nu de definitie die in het corresponderende register is opgeslagen.

// Create your custom registry.
const registry = new CustomElementRegistry();
// Define a custom element in the new registry.
registry.define('my-card', class extends HTMLElement {
  connectedCallback() {
    this.textContent = 'Hello from scoped registry!';
  }
});

// Create shadow root, providing it with your new custom element registry.
const host = document.querySelector('#host');
const shadow = host.attachShadow({
  mode: 'open',
  customElementRegistry: registry,
});

shadow.innerHTML = '<my-card></my-card>';

Declaratieve schaduw-DOM

Gebruik het attribuut shadowrootcustomelementregistry op een <template> -element om de browser te laten weten dat de resulterende shadow root een scoped registry gebruikt in plaats van de globale registry:

<my-host>
  <template shadowrootmode="open" shadowrootcustomelementregistry>
    <my-widget></my-widget>
  </template>
</my-host>

  const registry = new CustomElementRegistry();
  registry.define('my-widget', class extends HTMLElement {
    connectedCallback() { this.textContent = 'Scoped!'; }
  });

  const shadow = document.querySelector('my-host').shadowRoot;
  registry.initialize(shadow);

Zoals in het voorbeeld te zien is, reserveert het attribuut ruimte voor het register van aangepaste elementen. De gebruiker moet het register definiëren en initialiseren naar de shadow root, die is gekoppeld aan een losgekoppeld document.

Je kunt een register ook koppelen aan een document, bijvoorbeeld een document dat is gemaakt met document.implementation.createHTMLDocument() . Hiermee kun je <template> -elementen klonen en documentmanipulatie buiten het scherm uitvoeren, elk met hun eigen geïsoleerde set componentdefinities. Gebruik hiervoor de methode CustomElementRegistry.initialize() :

// Create a new registry.
const registry = new CustomElementRegistry();
registry.define('app-widget', AppWidget);

// Create a document, and use registry.initialize() to scope the registry to the document.
const doc = document.implementation.createHTMLDocument('');
registry.initialize(doc);

doc.body.innerHTML = '<app-widget></app-widget>';

Reikwijdte tot een individueel element

Je kunt een register ook rechtstreeks aan een element en de bijbehorende substructuur koppelen door de optie customElementRegistry door te geven aan document.createElement() . Het element en zijn afstammelingen zullen dan aan dat register worden gekoppeld, ongeacht in welk deel van de DOM ze later worden ingevoegd.

// Create a registry and define a custom element in it.
const registry = new CustomElementRegistry();
registry.define('fancy-label', FancyLabel);

// Create a new DOM element and scope the new registry to it.
const el = document.createElement('fancy-input', {
  customElementRegistry: registry,
});

// Use a custom element in the new DOM element.
el.innerHTML = '<fancy-label>Name</fancy-label>';

Leer meer

Voor meer informatie kunt u de Edge-demo en de bijbehorende broncode bekijken en het referentieartikel over CustomElementRegistry op MDN lezen.

Dankzij onze samenwerking binnen het Chromium-project zijn scoped custom element registries nu standaard ingeschakeld in zowel Microsoft Edge als Chrome, en ook in andere op Chromium gebaseerde browsers.

Je hoeft geen instellingen in te schakelen of je aan te melden voor een Origin-proefversie. Je kunt de functie vandaag nog gebruiken in browsers die op Chromium gebaseerd zijn.

Als je wilt dat deze functie ook in andere browsers wordt geïmplementeerd, geef dan een duim omhoog aan het issue 'Scoped custom element registries' en laat een reactie achter met je gebruiksscenario's en oplossingen.

Als je een bug vindt in de implementatie van de functie in een op Chromium gebaseerde browser, open dan een issue op crbug.com/new zodat we deze kunnen onderzoeken.

We hopen dat aangepaste elementregisters met een beperkt bereik het gebruik van webcomponenten vereenvoudigen.