Thedefine() method of theCustomElementRegistry 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.

Syntax

define(name, constructor)define(name, constructor, options)

Parameters

name

Name for the new custom element. Must be avalid custom element name.

constructor

Constructor for the new custom element.

optionsOptional

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

extends

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

Return value

None (undefined).

Exceptions

NotSupportedErrorDOMException

Thrown if:

• TheCustomElementRegistry already contains an entry with the same name or the same constructor (or is otherwise already defined).
• Theextends option is specified and it is avalid custom element name
• Theextends option is specified but the element it is trying to extend is an unknown element.

SyntaxErrorDOMException

Thrown if the provided name is not avalid custom element name.

TypeError

Thrown if the referenced constructor is not a constructor.

Description

Thedefine() 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:

• Autonomous custom elements are standalone elements, that don't inherit from built-in HTML elements.
• Customized built-in elements are elements that inherit from, and extend, built-in HTML elements.

To define an autonomous custom element, you should omit theoptions parameter.

To define a customized built-in element, you must pass theoptions parameter with itsextends 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"} todefine(), and the class definition for your element must inherit fromHTMLParagraphElement.

Valid custom element names

Custom element names must:

• start with an ASCII lowercase letter (a-z)
• contain a hyphen
• not contain any ASCII uppercase letters
• not contain certain other characters, as documented in thevalid custom element names section of the Web Components specification
• not be any of:
  • "annotation-xml"
  • "color-profile"
  • "font-face"
  • "font-face-src"
  • "font-face-uri"
  • "font-face-format"
  • "font-face-name"
  • "missing-glyph"

Examples

Defining an autonomous custom element

The following class implements a minimal autonomous custom element:

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. SeeImplementing a custom element in our guide to working with custom elements.

However, the above class definition satisfies the requirements of thedefine() method, so we can define it with the following code:

customElements.define("my-autonomous-element", MyAutonomousElement);

We could then use it in an HTML page like this:

<my-autonomous-element>Element contents</my-autonomous-element>

Defining a customized built-in element

The following class implements a customized built-in element:

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 ofdefine(), so we can define it like this:

customElements.define(  "my-customized-built-in-element",  MyCustomizedBuiltInElement,  {    extends: "p",  },);

We could then use it in an HTML page like this:

<p is="my-customized-built-in-element"></p>

Specifications

Browser compatibility

See also

• Using custom elements