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 NotSupportedError
s 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 (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 (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 Standard The 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.
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
define | Chrome
Full support
66
| Edge
Full support
79
| Firefox
Full support
63
| IE No support No | Opera
Full support
53
| Safari
Full support
10.1
| WebView Android
Full support
66
| Chrome Android
Full support
66
| Firefox Android
Full support
63
| Opera Android
Full support
47
| Safari iOS
Full support
10.3
| Samsung Internet Android
Full support
9.0
|
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.