Skip to content
Tutorials Center
My learning

Topics

JavaScript Reference ยท DOM: Document and Elements

Custom elements

Reference for custom elements: customElements.define(), lifecycle callbacks, observedAttributes, naming rules, upgrades and customized built-ins, with live examples.

Custom elements let you define your own HTML tags, such as <user-card> or <star-rating>, whose behavior is written in JavaScript. You write a class that extends HTMLElement, register it with customElements.define(), and from then on the browser creates instances of that class wherever the tag appears, in HTML or through document.createElement().

They are one of the pillars of web components, together with shadow DOM and templates.

JavaScript
class HelloTag extends HTMLElement {
  connectedCallback() {
    this.textContent = "Hello!";
  }
}
customElements.define("hello-tag", HelloTag);

Try it

A counter element
Reacting to attributes

Syntax

JavaScript
customElements.define(name, constructor)
customElements.define(name, constructor, { extends: "button" })
customElements.get(name)
customElements.whenDefined(name)
customElements.upgrade(root)

Parameters

Name Description
name The tag name. It must be lowercase, contain a hyphen and start with a letter (my-widget, not widget). Some reserved names such as annotation-xml and font-face are not allowed.
constructor A class extending HTMLElement (or another built-in element class for customized built-ins).
options.extends Name of a built-in tag to extend, for customized built-ins used as <button is="my-button">.

Lifecycle callbacks

Callback When it runs
constructor() When the element is created or upgraded. Call super() first.
connectedCallback() Every time the element is inserted into a document.
disconnectedCallback() Every time it is removed.
adoptedCallback() When it moves to another document.
attributeChangedCallback(name, old, new) For each attribute listed in the static observedAttributes array that is added, changed or removed.

Return value and exceptions

define() returns undefined and throws NotSupportedError if the name or the class is already registered, and SyntaxError for an invalid name. whenDefined() returns a promise that resolves when the element is defined.

Usage notes

  • Do little in the constructor. Do not read attributes, children or add children there: when the parser creates the element, they may not exist yet, and createElement() forbids attributes and children being added in the constructor. Do the setup in connectedCallback().
  • connectedCallback() can run many times, once for each insertion. Guard one-time work, such as creating child elements, with a flag.
  • Upgrades. If the HTML contains <my-tag> before define() runs, it is an ordinary unknown element until the definition arrives, and is then upgraded in place. Style with my-tag:not(:defined) to avoid a flash of unstyled content.
  • Attributes versus properties. Reflect important state to attributes yourself, in getters and setters. Attribute values are always strings.
  • Extending built-ins (is="...") is not supported by every browser. Prefer autonomous elements, wrapping a built-in element inside.
  • Self-closing is not allowed. Write <my-tag></my-tag>, never <my-tag />.
  • Form participation and accessibility. Autonomous elements are not form controls by default. static formAssociated = true plus ElementInternals lets them take part in forms, and ARIA roles are set through this.internals.role or attributes.
  • Use a prefix for your names to avoid clashing with future built-in elements and other libraries.

Browser support

Autonomous custom elements work in all current browsers. Customized built-ins (is=) are not supported everywhere, and ElementInternals form association is more recent, so check a compatibility table.