liveBook · Manning

CustomElementRegistry

As explained in Vanilla Web

The browser registry interface for defining and retrieving custom element constructors.

A custom element class does not become available to a page merely because its JavaScript has loaded. The browser’s CustomElementRegistry, exposed as customElements, associates a tag name with its constructor. It is one native building block of web components, alongside Shadow DOM, HTML templates, and Element Internals. section 7.5 section 7.6.5

customElements.define('symbol-bitcoin', BitcoinSymbol);

Call define(name, constructor) to register the element. The name must contain a hyphen and must not already be registered. An optional extends setting registers a customized built-in element. section 7.6.3

Use the registered element

After registration, use <symbol-bitcoin></symbol-bitcoin> in HTML or create it with document.createElement('symbol-bitcoin'). Do not use a self-closing tag. The browser creates an instance of the registered class; its connectedCallback runs when the element is attached to the DOM. If the name was never registered, the HTML produces an empty HTMLElement rather than an error. section 7.6.3

The registry also supports availability checks and deferred work:

  • customElements.get(name) returns the registered constructor, or undefined. section 7.6.5
  • customElements.whenDefined(name) returns a promise that resolves when registration occurs. section 7.6.5
  • customElements.upgrade(root) upgrades registered custom elements within a subtree when its markup was created before registration; it is rarely needed. section 7.6.5

How Vanilla Web covers it

How deep it goes
Explains registration constraints and three helper methods, while deferring customized built-ins and detailed lifecycle behavior.
Examples
Registers a Bitcoin-symbol element and uses its tag in HTML and document.createElement().
What it assumes
Assumes familiarity with JavaScript constructors and HTML elements while explaining how registration makes a constructor available to the page.
What you can do after
Apply it via customElements to register a constructor, check its availability, or wait for its definition.
How it connects
Connects Custom Elements to Shadow DOM, HTML templates, Element Internals, and DOM creation.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Vanilla Web. The section links point to the parts of the book it draws on.