JavaScript Document customElementRegistry Property

What You’ll Learn

Document.customElementRegistry is a read-only instance property that returns the CustomElementRegistry for this document, or null. Learn how it relates to window.customElements, why some created documents have a null registry, how ShadowRoot shares the same property name, and five examples with try-it labs.

Introduction

Custom elements let you invent HTML tags like <my-card>. The browser keeps a registry of those tag names and their class definitions. Most tutorials use window.customElements (or just customElements) to call define(), get(), and whenDefined().

document.customElementRegistry is the Document’s way to reach that registry object. MDN: for documents associated with a Window (a normal page), it is the same global registry as window.customElements. Documents created with createHTMLDocument() often have null by default.

Related Document tutorials: currentScript, cookie, Document constructor.

Understanding Document.customElementRegistry

A read-only instance property on Document. Value is a CustomElementRegistry or null.

• Main page document — usually equals window.customElements (MDN).
• Programmatic documents — createHTMLDocument() defaults to null (MDN).
• ShadowRoot — same property name for scoped registries (MDN).
• Use the registry — define(), get(), whenDefined(), getName() (where supported).
• Not assignable — you read the registry; you do not assign a new one via this property.

📝 Syntax

document.customElementRegistry

Value

A CustomElementRegistry object, or null.

Safe read (feature-detect)

const registry =
  "customElementRegistry" in document
    ? document.customElementRegistry
    : (window.customElements || null);

console.log(registry);

⚖️ Registry accessors compared

Examples Gallery

Examples follow MDN Document: customElementRegistry. Feature-detect in unsupported browsers. Use View Output or Try It Yourself for each case.

// Main document registry is the global one (when supported):
console.log(
  document.customElementRegistry === window.customElements
); // true on Window-associated documents

true

const newDoc = document.implementation.createHTMLDocument("New document");
console.log(newDoc.customElementRegistry); // null (MDN)

null

const hasDocProp = "customElementRegistry" in document;
const registry = hasDocProp
  ? document.customElementRegistry
  : window.customElements;

console.log("Document property present:", hasDocProp);
console.log("Using registry:", !!registry);

Document property present: true
Using registry: true

const registry =
  document.customElementRegistry || window.customElements;

if (registry && !registry.get("hello-chip")) {
  registry.define(
    "hello-chip",
    class extends HTMLElement {
      connectedCallback() {
        this.textContent = this.textContent || "Hello custom element!";
      }
    }
  );
}

document.body.appendChild(document.createElement("hello-chip"));

(page shows: Hello custom element!)

const host = document.createElement("div");
const root = host.attachShadow({ mode: "open" });

console.log(
  "ShadowRoot has customElementRegistry:",
  "customElementRegistry" in root
);
console.log("shadow registry:", root.customElementRegistry);
// May be null or a scoped/global registry depending on browser & options

ShadowRoot has customElementRegistry: true
shadow registry: null

🚀 Common Use Cases

• Read the document registry explicitly — when APIs take a CustomElementRegistry object.
• Null checks — before defining elements on programmatically created documents.
• Scoped registries — micro-frontends / component libraries isolating tag names (advanced).
• ShadowRoot association — inspect which registry a shadow tree uses.
• Teaching / debugging — prove main document === window.customElements.
• Prefer customElements for basics — wider support for everyday define().

📝 Notes

• MDN: Limited availability (not Baseline) — no Deprecated / Experimental / Non-standard banner on MDN for this page.
• Read-only; value is CustomElementRegistry or null.
• Main Window documents: same object as window.customElements (MDN).
• Also available on ShadowRoot under the same name (MDN).
• Feature-detect; fall back to window.customElements for basic custom elements.
• Related: currentScript, cookie, Document constructor.

💡 Best Practices