CustomElementRegistry.define

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

Syntax

customElements.define(name, constructor, options);

Parameters

name

Name for the new custom element.

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.

Examples

Autonomous custom element

The constructors for these elements must extend HTMLElement.

class BasicElement extends HTMLElement {
  connectedCallback() {
    this.textContent = 'Just a basic custom element.';
  }
}
customElements.define('basic-element', BasicElement);

<basic-element><basic-element>

Customized built-in element

Note: Though defined in the spec, this is not presently supported in browsers.

Besides whatever enhancements we add, the following will otherwise behave like a <button>:

class PlasticButton extends HTMLButtonElement {
  constructor() {
    super();

    this.addEventListener("click", () => {
      // Draw some fancy animation effects!
    });
  }
}

// The "extends" attribute is required for, and only usable by,
//    customized built-in-elements

customElements.define("plastic-button", PlasticButton, { extends: "button" });

<!-- This *WILL* work -->

<button is="plastic-button">Click Me!</button>

<!--
The following autonomous custom element style will *NOT* work because of
our definition in JavaScript above using "extends". The element below will
thus not gain the above-defined behavior nor be any different from any other
unknown HTML element.
-->

<plastic-button>Click me</plastic-button>

Specifications

Browser compatibility

[1] While Firefox does not yet support customElements.define(), it still supports the deprecated document.registerElement().