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
-
NotSupportedError
DOMException
-
Thrown if the
CustomElementRegistry
already contains an entry with the same name or the same constructor (or is otherwise already defined), orextends
is specified and it is a valid custom element name, orextends
is specified but the element it is trying to extend is an unknown element. -
SyntaxError
DOMException
-
Thrown if the provided name is not a valid custom element name.
-
TypeError
DOMException
-
Thrown if 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>
Creating an element which disables the ability to attach a shadow root
If the class used for the element contains the static property disabledFeatures
returning the string `shadow` this will cause Element.attachShadow()
to return a DOMException
NotSupportedError
.
class PopUpInfo extends HTMLElement { static get disabledFeatures() { return ['shadow']; } constructor() { super(); var shadow = this.attachShadow({mode: 'open'}); // this will cause an error to be thrown when the element is defined. } }
Specifications
Browser compatibility
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
Chrome | Edge | Firefox | Internet Explorer | Opera | Safari | WebView Android | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | |
define |
67
Support for 'Customized built-in elements' as well.
54
Support for 'Autonomous custom elements' only.
|
79
Support for 'Customized built-in elements' as well.
79
Support for 'Autonomous custom elements' only.
|
63 |
No |
54
Support for 'Customized built-in elements' as well.
41
Support for 'Autonomous custom elements' only.
|
10.1
Supports 'Autonomous custom elements' but not 'Customized built-in elements'
|
67
Support for 'Customized built-in elements' as well.
54
Support for 'Autonomous custom elements' only.
|
67
Support for 'Customized built-in elements' as well.
54
Support for 'Autonomous custom elements' only.
|
63 |
48
Support for 'Customized built-in elements' as well.
41
Support for 'Autonomous custom elements' only.
|
10.3
Supports 'Autonomous custom elements' but not 'Customized built-in elements'
|
9.0
Support for 'Customized built-in elements' as well.
6.0
Support for 'Autonomous custom elements' only.
|
© 2005–2021 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define