Limited support Use with care and provide a fallback when broad support matters.

Scoped custom element registries

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.

Web Components

Browser support

Feature Desktop Mobile
Chrome
Edge
Firefox
Safari
Chrome Android
Safari iOS
api.CustomElementRegistry.CustomElementRegistry
146
146
26
146
26
DOM API
initialize

The initialize() method of the CustomElementRegistry interface associates this registry with a DOM subtree, setting the Element.customElementRegistry of each inclusive descendant that doesn't already have one, and attempting to upgrade any custom elements found.
146
146
26
146
26
customElementRegistry

The customElementRegistry read-only property of the Document interface returns the CustomElementRegistry object associated with this document, or null if one has not been set.
146
146
150
26
146
26
customElementRegistry

The customElementRegistry read-only property of the Element interface returns the CustomElementRegistry object associated with this element, or null if one has not been set.
146
146
150
26
146
26
shadowRootCustomElementRegistry

The shadowRootCustomElementRegistry property of the HTMLTemplateElement interface reflects the value of the shadowrootcustomelementregistry attribute of the associated element.
146
146
26
146
26
customElementRegistry

The customElementRegistry read-only property of the ShadowRoot interface returns the CustomElementRegistry object associated with this shadow root, or null if one has not been set.
146
146
150
26
146
26
1+Supported (version) Not supported ※Has note Sub-feature descriptions sourced from MDN Web Docs (CC BY-SA 2.5)
Notes 1 item(s)
Experimental
  • Requires an experimental browser flag to be enabled
Notes 1 item(s)
Experimental
  • Requires an experimental browser flag to be enabled
Notes 1 item(s)
Experimental
  • Requires an experimental browser flag to be enabled

Syntax

JAVASCRIPT 
const registry = new CustomElementRegistry();
registry.define('my-el', MyElement);
const shadow = host.attachShadow({
  mode: 'open',
  registry
});

Live demo

Scoped registry idea

Show how a local custom element registry can avoid global name collisions.

PreviewFullscreen

Why it matters

Scoped registries help larger component ecosystems avoid global coordination for every tag name.

PreviewFullscreen

Adoption trade-off

Use scoped registries only when your component model actually benefits from local registration boundaries.

PreviewFullscreen

Use cases

  • Use Scoped custom element registries

    Use Scoped custom element registries when standard HTML needs a more specific platform feature, semantic signal, or browser capability.

  • Handle edge cases

    Apply Scoped custom element registries to solve a focused requirement without redesigning the whole page architecture.

Cautions

  • Test Scoped custom element registries in your target browsers and input environments before depending on it as a primary behavior.
  • Provide a fallback path or acceptable degradation strategy when support is still limited.

Accessibility

  • Make sure Scoped custom element registries supports the intended task without making the page harder to perceive, understand, or operate.

Related links