HTML shadowrootcustomelementregistry Attribute

HTML shadowrootcustomelementregistry Attribute

The HTML shadowrootcustomelementregistry attribute is a boolean attribute used with a declarative shadow DOM <template>. When present with shadowrootmode, it creates a shadow root without automatically using the document's custom element registry, allowing a scoped CustomElementRegistry to be attached later.

Elements That Use the shadowrootcustomelementregistry Attribute

The shadowrootcustomelementregistry attribute is used with the <template> element when declaring a shadow root.

Boolean Attribute

The shadowrootcustomelementregistry attribute is a boolean attribute. Its presence tells the browser not to automatically associate the resulting declarative shadow root with the document's custom element registry.

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

Because it is a boolean attribute, the presence of shadowrootcustomelementregistry is what matters. It does not need a value such as true or false.

How shadowrootcustomelementregistry Works

Normally, a declarative shadow root uses the custom element registry associated with the document. When shadowrootcustomelementregistry is present, the resulting shadow root's custom element registry is initially null instead.

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

This allows a separate CustomElementRegistry to be associated with the shadow root later. Custom element definitions in that registry can then be scoped to the shadow tree instead of relying on the document's global registry.

Using shadowrootcustomelementregistry with shadowrootmode

The shadowrootcustomelementregistry attribute does not create a shadow root by itself. It is used with a valid shadowrootmode="open" or shadowrootmode="closed" attribute on the same <template>.

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

The shadowrootmode attribute declares the shadow root, while shadowrootcustomelementregistry specifies that its custom element registry should initially be null so a scoped registry can be attached later.

Scoped Custom Element Registries

A scoped custom element registry allows custom element definitions to be associated with a particular shadow root rather than using only the document's global custom element registry. This can allow separate parts of a page to use their own custom element definitions.

After a declarative shadow root has been created with shadowrootcustomelementregistry, JavaScript can create a CustomElementRegistry, define custom elements in it, and associate that registry with the shadow root using its initialize() method.

const registry = new CustomElementRegistry();

registry.define("my-widget", class extends HTMLElement {
  connectedCallback() {
    this.textContent = "Scoped custom element";
  }
});

registry.initialize(document.querySelector("#component").shadowRoot);

Once initialized, elements within that shadow tree use the scoped registry for their custom element definitions.

Common Mistakes

Do not use shadowrootcustomelementregistry without a valid shadowrootmode attribute when you intend to create a declarative shadow root. The attribute does not create a shadow root by itself.

Do not write shadowrootcustomelementregistry="false" to disable the feature. Because it is a boolean attribute, its presence enables the behavior. Omit the attribute when the declarative shadow root should use its normal registry behavior.

Do not assume that shadowrootcustomelementregistry automatically creates or attaches a new CustomElementRegistry. It leaves the resulting shadow root without a registry so a scoped registry can be associated later.

Do not confuse shadowrootcustomelementregistry with shadowrootmode. The first controls the initial custom element registry behavior, while the second declares the shadow root and determines whether its mode is open or closed.

Browser Support

Baseline: Limited availability indicates that a feature is not yet available in all core browsers. Use these features with caution because they may only work in select browsers, so additional compatibility checks may be needed before general use.

The shadowrootcustomelementregistry attribute on the <template> element has limited availability and should be tested before it is relied on for production use.

Checking Browser Support

For current browser compatibility information, visit Can I Use? . Search for the HTML element or attribute you want to check. You can also narrow your search by entering an element name and attribute name separated by a colon. Search results can include related HTML features, element attributes, input types, APIs, and other technologies, so select the result that most closely matches the feature you are checking.

Try the shadowrootcustomelementregistry Attribute

The example creates an open declarative shadow root with shadowrootcustomelementregistry. The custom element inside the shadow root is displayed as an undefined custom element until a scoped custom element registry is associated with the shadow root in supporting browsers.

Summary

The HTML shadowrootcustomelementregistry attribute is a boolean attribute used with a declarative shadow DOM <template>. When combined with a valid shadowrootmode attribute, it causes the resulting shadow root's custom element registry to initially be null, allowing a scoped CustomElementRegistry to be associated with the shadow root later.