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
