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


Defines a new custom element.
Returns the constructor for the named custom element, or undefined if the custom element is not defined.
Upgrades a custom element directly, even before it is connected to its shadow root.
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.


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

    // 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

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


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

Browser compatibility

BCD tables only load in the browser