Web/API/CustomElementRegistry

The CustomElementRegistry interface provides methods for registering custom elements and querying registered elements. To get an instance of it, use the window.customElements property.

Methods

CustomElementRegistry.define(): Defines a new custom element.
CustomElementRegistry.get(): Returns the constuctor for the named custom element, or undefined if the custom element is not defined.
CustomElementRegistry.upgrade(): Upgrades a custom element directly, even before it is connected to its shadow root.
CustomElementRegistry.whenDefined(): Returns an empty promise that resolves when a custom element becomes defined with the given name. If such a custom element is already defined, the returned promise is immediately fulfilled.

Examples

The following code is taken from our word-count-web-component example ([[../../../../../../mdn.github.io/web-components-examples/word-count-web-component/index|see it live also]]). Note how we use the CustomElementRegistry.define() method to define the custom element after creating its class.

// Create a class for the element
class WordCount extends HTMLParagraphElement {
  constructor() {
    // Always call super first in constructor
    super();

    // count words in element's parent element
    var wcParent = this.parentNode;

    function countWords(node){
      var text = node.innerText || node.textContent
      return text.split(/\s+/g).length;
    }

    var count = 'Words: ' + countWords(wcParent);

    // Create a shadow root
    var shadow = this.attachShadow({mode: 'open'});

    // Create text node and add word count to it
    var text = document.createElement('span');
    text.textContent = count;

    // Append it to the shadow root
    shadow.appendChild(text);


    // Update count when element content changes
    setInterval(function() {
      var count = 'Words: ' + countWords(wcParent);
      text.textContent = count;
    }, 200)

  }
}

// Define the new element
customElements.define('word-count', WordCount, { extends: 'p' });

Note: The CustomElementRegistry is available through the Window.customElements property.

Specifications

Specification	Status	Comment
HTML Living StandardThe definition of 'CustomElementRegistry' in that specification.	Living Standard	Initial definition.

Browser compatibility

Update compatibility data on GitHub

	Desktop						Mobile
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	Android webview	Chrome for Android	Firefox for Android	Opera for Android	Safari on iOS	Samsung Internet
`CustomElementRegistry` Experimental'	Chrome Full support 54	Edge Full support 79	Firefox Full support 63 Full support 63 No support 59 — 63 Disabled' Disabled' From version 59 until version 63 (exclusive): this feature is behind the `dom.webcomponents.customelements.enabled` preference (needs to be set to `true`). To change preferences in Firefox, visit about:config. No support ? — 59 Disabled' Disabled' Until version 59 (exclusive): this feature is behind the `dom.webcomponents.enabled` preference (needs to be set to `true`) and the `dom.webcomponents.customelements.enabled` preference (needs to be set to `true`). To change preferences in Firefox, visit about:config.	IE No support No	Opera Full support 41	Safari Full support 10.1	WebView Android Full support 54	Chrome Android Full support 54	Firefox Android Full support 63 Full support 63 No support 59 — 63 Disabled' Disabled' From version 59 until version 63 (exclusive): this feature is behind the `dom.webcomponents.customelements.enabled` preference (needs to be set to `true`). To change preferences in Firefox, visit about:config. No support ? — 59 Disabled' Disabled' Until version 59 (exclusive): this feature is behind the `dom.webcomponents.enabled` preference (needs to be set to `true`) and the `dom.webcomponents.customelements.enabled` preference (needs to be set to `true`). To change preferences in Firefox, visit about:config.	Opera Android Full support 41	Safari iOS Full support 10.3	Samsung Internet Android Full support 6.0
Customized built-in element support Experimental'	Chrome Full support 66	Edge Full support 79	Firefox Full support 63 Full support 63 No support 59 — 63 Disabled' Disabled' From version 59 until version 63 (exclusive): this feature is behind the `dom.webcomponents.customelements.enabled` preference (needs to be set to `true`). To change preferences in Firefox, visit about:config. No support ? — 59 Disabled' Disabled' Until version 59 (exclusive): this feature is behind the `dom.webcomponents.enabled` preference (needs to be set to `true`) and the `dom.webcomponents.customelements.enabled` preference (needs to be set to `true`). To change preferences in Firefox, visit about:config.	IE No support No	Opera Full support 53	Safari No support No	WebView Android Full support 66	Chrome Android Full support 66	Firefox Android Full support 63 Full support 63 No support 59 — 63 Disabled' Disabled' From version 59 until version 63 (exclusive): this feature is behind the `dom.webcomponents.customelements.enabled` preference (needs to be set to `true`). To change preferences in Firefox, visit about:config. No support ? — 59 Disabled' Disabled' Until version 59 (exclusive): this feature is behind the `dom.webcomponents.enabled` preference (needs to be set to `true`) and the `dom.webcomponents.customelements.enabled` preference (needs to be set to `true`). To change preferences in Firefox, visit about:config.	Opera Android Full support 47	Safari iOS No support No	Samsung Internet Android Full support 9.0
`define` Experimental'	Chrome Full support 66 Notes' Full support 66 Notes' Notes' Support for 'Customized built-in elements' as well. Full support 54 Notes' Notes' Support for 'Autonomous custom elements' only.	Edge Full support 79 Notes' Full support 79 Notes' Notes' Support for 'Customized built-in elements' as well. Full support 79 Notes' Notes' Support for 'Autonomous custom elements' only.	Firefox Full support 63 Full support 63 No support 59 — 63 Disabled' Disabled' From version 59 until version 63 (exclusive): this feature is behind the `dom.webcomponents.customelements.enabled` preference (needs to be set to `true`). To change preferences in Firefox, visit about:config. No support ? — 59 Disabled' Disabled' Until version 59 (exclusive): this feature is behind the `dom.webcomponents.enabled` preference (needs to be set to `true`) and the `dom.webcomponents.customelements.enabled` preference (needs to be set to `true`). To change preferences in Firefox, visit about:config.	IE No support No	Opera Full support 53 Notes' Full support 53 Notes' Notes' Support for 'Customized built-in elements' as well. Full support 41 Notes' Notes' Support for 'Autonomous custom elements' only.	Safari Full support 10.1 Notes' Full support 10.1 Notes' Notes' Supports 'Autonomous custom elements' but not 'Customized built-in elements'	WebView Android Full support 66 Notes' Full support 66 Notes' Notes' Support for 'Customized built-in elements' as well. Full support 54 Notes' Notes' Support for 'Autonomous custom elements' only.	Chrome Android Full support 66 Notes' Full support 66 Notes' Notes' Support for 'Customized built-in elements' as well. Full support 54 Notes' Notes' Support for 'Autonomous custom elements' only.	Firefox Android Full support 63 Full support 63 No support 59 — 63 Disabled' Disabled' From version 59 until version 63 (exclusive): this feature is behind the `dom.webcomponents.customelements.enabled` preference (needs to be set to `true`). To change preferences in Firefox, visit about:config. No support ? — 59 Disabled' Disabled' Until version 59 (exclusive): this feature is behind the `dom.webcomponents.enabled` preference (needs to be set to `true`) and the `dom.webcomponents.customelements.enabled` preference (needs to be set to `true`). To change preferences in Firefox, visit about:config.	Opera Android Full support 47 Notes' Full support 47 Notes' Notes' Support for 'Customized built-in elements' as well. Full support 41 Notes' Notes' Support for 'Autonomous custom elements' only.	Safari iOS Full support 10.3 Notes' Full support 10.3 Notes' Notes' Supports 'Autonomous custom elements' but not 'Customized built-in elements'	Samsung Internet Android Full support 9.0 Notes' Full support 9.0 Notes' Notes' Support for 'Customized built-in elements' as well. Full support 6.0 Notes' Notes' Support for 'Autonomous custom elements' only.
`get` Experimental'	Chrome Full support 66 Notes' Full support 66 Notes' Notes' Support for 'Customized built-in elements' as well. Full support 54 Notes' Notes' Support for 'Autonomous custom elements' only.	Edge Full support 79 Notes' Full support 79 Notes' Notes' Support for 'Customized built-in elements' as well. Full support 79 Notes' Notes' Support for 'Autonomous custom elements' only.	Firefox Full support 63 Full support 63 No support 59 — 63 Disabled' Disabled' From version 59 until version 63 (exclusive): this feature is behind the `dom.webcomponents.customelements.enabled` preference (needs to be set to `true`). To change preferences in Firefox, visit about:config. No support ? — 59 Disabled' Disabled' Until version 59 (exclusive): this feature is behind the `dom.webcomponents.enabled` preference (needs to be set to `true`) and the `dom.webcomponents.customelements.enabled` preference (needs to be set to `true`). To change preferences in Firefox, visit about:config.	IE No support No	Opera Full support 53 Notes' Full support 53 Notes' Notes' Support for 'Customized built-in elements' as well. Full support 41 Notes' Notes' Support for 'Autonomous custom elements' only.	Safari Full support 10.1 Notes' Full support 10.1 Notes' Notes' Supports 'Autonomous custom elements' but not 'Customized built-in elements'	WebView Android Full support 66 Notes' Full support 66 Notes' Notes' Support for 'Customized built-in elements' as well. Full support 54 Notes' Notes' Support for 'Autonomous custom elements' only.	Chrome Android Full support 66 Notes' Full support 66 Notes' Notes' Support for 'Customized built-in elements' as well. Full support 54 Notes' Notes' Support for 'Autonomous custom elements' only.	Firefox Android Full support 63 Full support 63 No support 59 — 63 Disabled' Disabled' From version 59 until version 63 (exclusive): this feature is behind the `dom.webcomponents.customelements.enabled` preference (needs to be set to `true`). To change preferences in Firefox, visit about:config. No support ? — 59 Disabled' Disabled' Until version 59 (exclusive): this feature is behind the `dom.webcomponents.enabled` preference (needs to be set to `true`) and the `dom.webcomponents.customelements.enabled` preference (needs to be set to `true`). To change preferences in Firefox, visit about:config.	Opera Android Full support 47 Notes' Full support 47 Notes' Notes' Support for 'Customized built-in elements' as well. Full support 41 Notes' Notes' Support for 'Autonomous custom elements' only.	Safari iOS Full support 10.3 Notes' Full support 10.3 Notes' Notes' Supports 'Autonomous custom elements' but not 'Customized built-in elements'	Samsung Internet Android Full support 9.0 Notes' Full support 9.0 Notes' Notes' Support for 'Customized built-in elements' as well. Full support 6.0 Notes' Notes' Support for 'Autonomous custom elements' only.
`upgrade` Experimental'	Chrome Full support 68	Edge Full support 79	Firefox Full support 63	IE No support No	Opera Full support 55	Safari ?	WebView Android Full support 68	Chrome Android Full support 68	Firefox Android Full support 63	Opera Android Full support 48	Safari iOS ?	Samsung Internet Android Full support 10.0
`whenDefined` Experimental'	Chrome Full support 66 Notes' Full support 66 Notes' Notes' Support for 'Customized built-in elements' as well. Full support 54 Notes' Notes' Support for 'Autonomous custom elements' only.	Edge Full support 79 Notes' Full support 79 Notes' Notes' Support for 'Customized built-in elements' as well. Full support 79 Notes' Notes' Support for 'Autonomous custom elements' only.	Firefox Full support 63 Full support 63 No support 59 — 63 Disabled' Disabled' From version 59 until version 63 (exclusive): this feature is behind the `dom.webcomponents.customelements.enabled` preference (needs to be set to `true`). To change preferences in Firefox, visit about:config. No support ? — 59 Disabled' Disabled' Until version 59 (exclusive): this feature is behind the `dom.webcomponents.enabled` preference (needs to be set to `true`) and the `dom.webcomponents.customelements.enabled` preference (needs to be set to `true`). To change preferences in Firefox, visit about:config.	IE No support No	Opera Full support 53 Notes' Full support 53 Notes' Notes' Support for 'Customized built-in elements' as well. Full support 41 Notes' Notes' Support for 'Autonomous custom elements' only.	Safari Full support 10.1 Notes' Full support 10.1 Notes' Notes' Supports 'Autonomous custom elements' but not 'Customized built-in elements'	WebView Android Full support 66 Notes' Full support 66 Notes' Notes' Support for 'Customized built-in elements' as well. Full support 54 Notes' Notes' Support for 'Autonomous custom elements' only.	Chrome Android Full support 66 Notes' Full support 66 Notes' Notes' Support for 'Customized built-in elements' as well. Full support 54 Notes' Notes' Support for 'Autonomous custom elements' only.	Firefox Android Full support 63 Full support 63 No support 59 — 63 Disabled' Disabled' From version 59 until version 63 (exclusive): this feature is behind the `dom.webcomponents.customelements.enabled` preference (needs to be set to `true`). To change preferences in Firefox, visit about:config. No support ? — 59 Disabled' Disabled' Until version 59 (exclusive): this feature is behind the `dom.webcomponents.enabled` preference (needs to be set to `true`) and the `dom.webcomponents.customelements.enabled` preference (needs to be set to `true`). To change preferences in Firefox, visit about:config.	Opera Android Full support 47 Notes' Full support 47 Notes' Notes' Support for 'Customized built-in elements' as well. Full support 41 Notes' Notes' Support for 'Autonomous custom elements' only.	Safari iOS Full support 10.3 Notes' Full support 10.3 Notes' Notes' Supports 'Autonomous custom elements' but not 'Customized built-in elements'	Samsung Internet Android Full support 9.0 Notes' Full support 9.0 Notes' Notes' Support for 'Customized built-in elements' as well. Full support 6.0 Notes' Notes' Support for 'Autonomous custom elements' only.

Legend

Full support: Full support
No support: No support
Compatibility unknown: Compatibility unknown
Experimental. Expect behavior to change in the future.': Experimental. Expect behavior to change in the future.
See implementation notes.': See implementation notes.
User must explicitly enable this feature.': User must explicitly enable this feature.

CustomElementRegistry by Mozilla Contributors is licensed under CC-BY-SA 2.5.