The define()
method of the CustomElementRegistry
interface adds a definition for a custom element to the custom element registry, mapping its name to the constructor which will be used to create it.
The define()
method of the CustomElementRegistry
interface adds a definition for a custom element to the custom element registry, mapping its name to the constructor which will be used to create it.
js
define(name, constructor) define(name, constructor, options)
name
Name for the new custom element. Must be a valid custom element name.
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.
None (undefined
).
NotSupportedError
DOMException
Thrown if:
CustomElementRegistry
already contains an entry with the same name or the same constructor (or is otherwise already defined).extends
option is specified and it is a valid custom element name
extends
option 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
Thrown if the referenced constructor is not a constructor.
The define()
method adds a definition for a custom element to the custom element registry, mapping its name to the constructor which will be used to create it.
There are two types of custom element you can create:
To define an autonomous custom element, you should omit the options
parameter.
To define a customized built-in element, you must pass the options
parameter with its extends
property set to the name of the built-in element that you are extending, and this must correspond to the interface that your custom element class definition inherits from. For example, to customize the <p>
element, you must pass {extends: "p"}
to define()
, and the class definition for your element must inherit from HTMLParagraphElement
.
Custom element names must:
The following class implements a minimal autonomous custom element:
js
class MyAutonomousElement extends HTMLElement { constructor() { super(); } }
This element doesn't do anything: a real autonomous element would implement its functionality in its constructor and in the lifecycle callbacks provided by the standard. See Implementing a custom element in our guide to working with custom elements.
However, the above class definition satisfies the requirements of the define()
method, so we can define it with the following code:
js
customElements.define("my-autonomous-element", MyAutonomousElement);
We could then use it in an HTML page like this:
html
<my-autonomous-element>Element contents</my-autonomous-element>
The following class implements a customized built-in element:
js
class MyCustomizedBuiltInElement extends HTMLParagraphElement { constructor() { super(); } }
This element extends the built-in <p>
element.
In this minimal example the element doesn't implement any customization, so it will behave just like a normal <p>
element. However, it does satisfy the requirements of define()
, so we can define it like this:
js
customElements.define( "my-customized-built-in-element", MyCustomizedBuiltInElement, { extends: "p", }, );
We could then use it in an HTML page like this:
html
<p is="my-customized-built-in-element"></p>
Specification |
---|
HTML Standard # dom-customelementregistry-define-dev |
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
Chrome | Edge | Firefox | Internet Explorer | Opera | Safari | WebView Android | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | |
define |
54 | 79 | 63 | No | 41 | 10.1 | 54 | 54 | 63 | 41 | 10.3 | 6.0 |
disabledFeatures_static_property |
77 | 79 | 92 | No | 64 | No | 77 | 77 | 92 | 55 | No | 12.0 |
© 2005–2023 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