CustomElementRegistry: CustomElementRegistry() constructor

The CustomElementRegistry() constructor creates a new CustomElementRegistry object for scoped usage.

The constructor is specifically used for creating scoped registries that limit custom element definitions to a particular scope, such as an element or ShadowRoot.

Note: The global CustomElementRegistry object associated with a Window is not created using this constructor; it is automatically created when the window is set up, and is accessible via the window.customElements property.

Syntax

new CustomElementRegistry()

Parameters

None.

Return value

A new CustomElementRegistry object.

Description

When you construct a CustomElementRegistry using new CustomElementRegistry(), the resulting registry is considered scoped. This means:

Custom element definitions added to it using define() are not globally available. They only apply to nodes that have been associated with this registry.
It does not support the extends option in define() (for creating customized built-in elements). Attempting to use extends with a scoped registry throws a NotSupportedError DOMException.

To associate a scoped registry with a DOM subtree, you can use the initialize() method, pass it to Element.attachShadow(), or use the Document.createElement() method's customElementRegistry option.

Examples

undefined

Creating a scoped custom element registry

This example creates a scoped registry, defines a custom element on it, and passes the registry to Element.attachShadow(). When HTML containing <my-element> is added to the shadow root, the element is upgraded using the scoped registry's definition.

const myRegistry = new CustomElementRegistry();

myRegistry.define(
  "my-element",
  class extends HTMLElement {
    connectedCallback() {
      this.textContent = "Hello from scoped registry!";
    }
  },
);

const host = document.createElement("div");
document.body.appendChild(host);
const shadow = host.attachShadow({
  mode: "open",
  customElementRegistry: myRegistry,
});
shadow.innerHTML = "<my-element></my-element>";

console.log(shadow.querySelector("my-element").textContent);
// "Hello from scoped registry!"

Specifications

HTML