Web/API/CustomElementRegistry/define

The define() method of the CustomElementRegistry interface defines a new custom element.

There are two types of custom elements you can create:

• Autonomous custom element: Standalone elements; they don't inherit from built-in HTML elements.
• Customized built-in element: These elements inherit from — and extend — built-in HTML elements.

Syntax

customElements.define(name, constructor, options);

Parameters

name

Name for the new custom element. Note that custom element names must contain a hyphen.

constructor

Constructor for the new custom element.

options Optional

Object that controls how the element is defined. One option is currently supported:

extends

• String specifying the name of a built-in element to extend. Used to create a customized built-in element.

Return value

Void.

Exceptions

Exception	Description
NotSupportedError	The CustomElementRegistry already contains an entry with the same name or the same constructor (or is otherwise already defined), or extends is specified and it is a valid custom element name, or extends is specified but the element it is trying to extend is an unknown element.
SyntaxError	The provided name is not a valid custom element name.
TypeError	The referenced constructor is not a constructor.

Note: You'll often get NotSupportedErrors thrown that seem like define() is failing, but instead it is likely a problem with Element.attachShadow().

Examples

Autonomous custom element

The following code is taken from our popup-info-box-web-component example ([[../../../../../../../mdn.github.io/web-components-examples/popup-info-box-web-component/index|see it live also]]).

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

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

    // Create spans
    var wrapper = document.createElement('span');
    wrapper.setAttribute('class','wrapper');
    var icon = document.createElement('span');
    icon.setAttribute('class','icon');
    icon.setAttribute('tabindex', 0);
    var info = document.createElement('span');
    info.setAttribute('class','info');

    // Take attribute content and put it inside the info span
    var text = this.getAttribute('text');
    info.textContent = text;

    // Insert icon
    var imgUrl;
    if(this.hasAttribute('img')) {
      imgUrl = this.getAttribute('img');
    } else {
      imgUrl = 'img/default.png';
    }
    var img = document.createElement('img');
    img.src = imgUrl;
    icon.appendChild(img);

    // Create some CSS to apply to the shadow dom
    var style = document.createElement('style');

    style.textContent = '.wrapper {' +
                           'position: relative;' +
                        '}' +

                         '.info {' +
                            'font-size: 0.8rem;' +
                            'width: 200px;' +
                            'display: inline-block;' +
                            'border: 1px solid black;' +
                            'padding: 10px;' +
                            'background: white;' +
                            'border-radius: 10px;' +
                            'opacity: 0;' +
                            'transition: 0.6s all;' +
                            'position: absolute;' +
                            'bottom: 20px;' +
                            'left: 10px;' +
                            'z-index: 3;' +
                          '}' +

                          'img {' +
                            'width: 1.2rem' +
                          '}' +

                          '.icon:hover + .info, .icon:focus + .info {' +
                            'opacity: 1;' +
                          '}';

    // attach the created elements to the shadow dom

    shadow.appendChild(style);
    shadow.appendChild(wrapper);
    wrapper.appendChild(icon);
    wrapper.appendChild(info);
  }
}

// Define the new element
customElements.define('popup-info', PopUpInfo);

<popup-info img="img/alt.png" text="Your card validation code (CVC) is an extra
                                    security feature — it is the last 3 or 4 
                                    numbers on the back of your card.">

Note: Constructors for autonomous custom elements must extend HTMLElement.

Customized built-in element

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]]).

// 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' });

<p is="word-count"></p>

Specifications

Specification	Status	Comment
HTML Living StandardThe definition of 'customElements.define()' in that specification.	Living Standard	Initial definition.

Browser compatibility

The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request.

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

Legend

Full support  

Full support

No support  

No support

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.define() by Mozilla Contributors is licensed under CC-BY-SA 2.5.