JavaScript Element customElementRegistry Property

What You’ll Learn

Element.customElementRegistry is a read-only instance property that returns the CustomElementRegistry tied to an element, or null. Learn how scoped registries work with shadow DOM, why the value is fixed after creation, and how to feature-detect—with five examples and try-it labs.

Introduction

Most pages register custom elements on the global registry: window.customElements. Scoped custom element registries let a shadow tree (or other subtree) use its own registry so tag names do not collide with the rest of the page.

element.customElementRegistry tells you which registry that element will use when it is upgraded—or null if none was associated.

if ("customElementRegistry" in Element.prototype) {
  console.log(el.customElementRegistry); // CustomElementRegistry or null
}

Understanding the Property

MDN: 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.

An element’s registry is set when the element is created (for example via Document.createElement() with a customElementRegistry option, or when parsed in a context that already has a scoped registry). Once set to a CustomElementRegistry, it cannot be changed. That registry decides which custom element definitions are used when the element is upgraded.

• Read-only — you cannot reassign the property later.
• Nullable — null means no registry was associated.
• Scoped APIs — often used with new CustomElementRegistry() and shadow roots.
• Limited availability — not Baseline; feature-detect always (MDN).

📝 Syntax

customElementRegistry

Value

A CustomElementRegistry object, or null.

📋 MDN Scoped Registry Example

MDN creates a scoped registry, attaches it to a shadow root, then confirms a child element reports the same registry:

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>";

const el = shadow.querySelector("my-element");
console.log(el.customElementRegistry === myRegistry); // true

Related learning: window.customElements, Document.customElementRegistry, ShadowRoot.customElementRegistry, and currentCSSZoom.

Examples Gallery

Examples follow MDN Element: customElementRegistry. Labs feature-detect so unsupported browsers show a clear message.

console.log("customElementRegistry" in Element.prototype);

true

const myRegistry = new CustomElementRegistry();
myRegistry.define("my-element", class extends HTMLElement {});
const host = document.createElement("div");
document.body.appendChild(host);
const shadow = host.attachShadow({
  mode: "open",
  customElementRegistry: myRegistry,
});
shadow.innerHTML = "<my-element></my-element>";
const el = shadow.querySelector("my-element");
console.log(el.customElementRegistry === myRegistry); // true

true

const myRegistry = new CustomElementRegistry();
console.log({
  sameAsGlobal: myRegistry === window.customElements,
  isRegistry: myRegistry instanceof CustomElementRegistry
});

{
  "sameAsGlobal": false,
  "isRegistry": true
}

const el = document.createElement("div");
const reg = el.customElementRegistry;
console.log(reg === null ? "null" : "has registry");

has registry

console.log({
  supported: "customElementRegistry" in Element.prototype,
  returns: "CustomElementRegistry | null",
  tip: "Set at creation; immutable once set; use for scoped CE",
  status: "Limited availability (not Baseline) — MDN"
});

{
  "supported": true,
  "returns": "CustomElementRegistry | null",
  "tip": "Set at creation; immutable once set; use for scoped CE",
  "status": "Limited availability (not Baseline) — MDN"
}

🚀 Common Use Cases

• Confirming a shadow tree is using your scoped CustomElementRegistry.
• Debugging why a custom tag upgraded with unexpected definitions.
• Building libraries that isolate tag names per component package.
• Teaching the difference between global customElements and scoped registries.
• Feature-detecting before shipping scoped-registry code paths.

🔧 How It Works

📝 Notes

• Not Deprecated, Experimental, or Non-standard on MDN/BCD (Limited availability / not Baseline).
• Read-only — once a registry is set, it cannot be changed.
• Feature-detect; Firefox may require a preference flag for scoped registries.
• Related: currentCSSZoom, elementTiming, EventTarget, JavaScript hub.

💡 Best Practices