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.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 (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 Standard
The definition of 'CustomElementRegistry' in that specification.
Living Standard Initial definition.

Browser compatibility

 

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidEdge MobileFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
Basic support
Experimental
Chrome Full support 54Edge No support No
Notes
No support No
Notes
Notes In Development
Firefox Full support 63
Full support 63
No support 59 — 65
Disabled
Disabled From version 59 until version 65 (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 NoOpera Full support 41Safari Full support 10.1WebView Android Full support 54Chrome Android Full support 54Edge Mobile No support No
Notes
No support No
Notes
Notes In Development
Firefox Android Full support 63
Full support 63
No support 59 — 65
Disabled
Disabled From version 59 until version 65 (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 41Safari iOS Full support 10.1Samsung Internet Android Full support 6.0
Customized built-in element support
Experimental
Chrome Full support 66Edge No support NoFirefox Full support 63
Full support 63
No support 59 — 65
Disabled
Disabled From version 59 until version 65 (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 NoOpera Full support 53Safari No support NoWebView Android Full support 66Chrome Android Full support 66Edge Mobile No support NoFirefox Android Full support 63
Full support 63
No support 59 — 65
Disabled
Disabled From version 59 until version 65 (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 53Safari iOS No support NoSamsung Internet Android No support No
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 No support No
Notes
No support No
Notes
Notes In Development
Firefox Full support 63
Full support 63
No support 59 — 65
Disabled
Disabled From version 59 until version 65 (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 NoOpera 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.
Edge Mobile No support No
Notes
No support No
Notes
Notes In Development
Firefox Android Full support 63
Full support 63
No support 59 — 65
Disabled
Disabled From version 59 until version 65 (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 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 iOS Full support 10.1
Notes
Full support 10.1
Notes
Notes Supports 'Autonomous custom elements' but not 'Customized built-in elements'
Samsung Internet Android Full support 6.0
Notes
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 No support No
Notes
No support No
Notes
Notes In Development
Firefox Full support 63
Full support 63
No support 59 — 65
Disabled
Disabled From version 59 until version 65 (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 NoOpera 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.
Edge Mobile No support No
Notes
No support No
Notes
Notes In Development
Firefox Android Full support 63
Full support 63
No support 59 — 65
Disabled
Disabled From version 59 until version 65 (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 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 iOS Full support 10.1
Notes
Full support 10.1
Notes
Notes Supports 'Autonomous custom elements' but not 'Customized built-in elements'
Samsung Internet Android Full support 6.0
Notes
Full support 6.0
Notes
Notes Support for 'Autonomous custom elements' only.
upgrade
Experimental
Chrome Full support 68Edge ? Firefox ? IE ? Opera Full support 55Safari ? WebView Android Full support 68Chrome Android Full support 68Edge Mobile ? Firefox Android ? Opera Android Full support 55Safari iOS ? Samsung Internet Android ?
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 No support No
Notes
No support No
Notes
Notes In Development
Firefox Full support 63
Full support 63
No support 59 — 65
Disabled
Disabled From version 59 until version 65 (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 NoOpera 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.
Edge Mobile No support No
Notes
No support No
Notes
Notes In Development
Firefox Android Full support 63
Full support 63
No support 59 — 65
Disabled
Disabled From version 59 until version 65 (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 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 iOS Full support 10.1
Notes
Full support 10.1
Notes
Notes Supports 'Autonomous custom elements' but not 'Customized built-in elements'
Samsung Internet Android Full support 6.0
Notes
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.

 

Document Tags and Contributors

Last updated by: pallxk,