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.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 CustomElementsRegistry 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

 

FeatureChromeEdgeFirefoxInternet ExplorerOperaSafari
Basic support54 No1

592

Yes — 593

No4110.1
Support for Customized built-in elements66 No

592

Yes — 593

No53 No
define

664

545

No1

592

Yes — 593

No

534

415

10.16
get

664

545

No1

592

Yes — 593

No

534

415

10.16
whenDefined

664

545

No1

592

Yes — 593

No

534

415

10.16
FeatureAndroid webviewChrome for AndroidEdge mobileFirefox for AndroidOpera AndroidiOS SafariSamsung Internet
Basic support5454 No1

592

Yes — 593

4110.16.0
Support for Customized built-in elements6666 No

592

Yes — 593

53 No No
define

664

545

664

545

No1

592

Yes — 593

534

415

10.166.05
get

664

545

664

545

No1

592

Yes — 593

534

415

10.166.05
whenDefined

664

545

664

545

No1

592

Yes — 593

534

415

10.166.05

1. Under consideration

2. From version 59: this feature is behind the dom.webcomponents.customelements.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.

3. 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.

4. Support for 'Customized built-in elements' as well.

5. Support for 'Autonomous custom elements' only.

6. Supports 'Autonomous custom elements' but not 'Customized built-in elements'

 

Document Tags and Contributors

 Last updated by: jpmedley,