Scoped custom element registries
The CustomElementRegistry() constructor creates a new custom element registry that's separate from the global window.customElements registry. Creating more than one registry is useful for multiple custom elements that have the same tag name to coexist. It is most useful when native HTML semantics or browser capabilities can replace custom implementation work.
Overview
The CustomElementRegistry() constructor creates a new custom element registry that's separate from the global window.customElements registry. Creating more than one registry is useful for multiple custom elements that have the same tag name to coexist. It is most useful when native HTML semantics or browser capabilities can replace custom implementation work.
Browser support
| Feature | Desktop | Mobile | ||||
|---|---|---|---|---|---|---|
| Chrome | Edge | Firefox | Safari | Chrome Android | Safari iOS | |
| 146 | 146 | | 26 | 146 | 26 | |
| DOM API | ||||||
| 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 |
| 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 |
| 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 |
| The shadowRootCustomElementRegistry property of the HTMLTemplateElement interface reflects the value of the shadowrootcustomelementregistry attribute of the associated element. | 146 | 146 | | 26 | 146 | 26 |
| 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 |
- Requires an experimental browser flag to be enabled
- Requires an experimental browser flag to be enabled
- Requires an experimental browser flag to be enabled
Syntax
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.
Why it matters
Scoped registries help larger component ecosystems avoid global coordination for every tag name.
Adoption trade-off
Use scoped registries only when your component model actually benefits from local registration boundaries.
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
Powered by web-features