Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / JavaScript

HTMLElement constructor

`HTMLElement` is the base class for autonomous custom elements. Invoke its constructor through `super()` in a subclass, not directly with `new HTMLElement()`.

Version: Current web platform; runtime support varies

Syntax

class StatusBadge extends HTMLElement {
  constructor() {
    super();
    // Initialize instance state here.
  }
}

customElements.define("cktis-status-badge", StatusBadge);

new StatusBadge();
document.createElement("cktis-status-badge");

The HTMLElement constructor is part of a web-platform interface exposed on Window, not an ECMAScript built-in. The class syntax dates to ECMAScript 2015, but the browser provides the HTML element constructor algorithm and the custom-element registry. Both new HTMLElement() and HTMLElement() throw TypeError. To create an ordinary HTML element, use document.createElement("div").

For an autonomous custom element, write a class that extends HTMLElement and register it with customElements.define() using a valid hyphenated name. If you write a constructor, put the no-argument super() call first, before using this. JavaScript passes new.target through to the base constructor, and the platform looks up the definition by constructor identity, not by a name passed to super(). Using new on an unregistered subclass throws TypeError when it reaches super().

Once registered, new StatusBadge() and document.createElement("cktis-status-badge") each create a new instance in the HTML namespace without inserting it into the document. When an existing element is upgraded to the registered class, super() makes that existing node available as this. Use the constructor for instance state; do not read or add attributes or child nodes there. Put work that needs the element to be connected in connectedCallback(), which can run more than once.

A customized built-in element needs the matching interface, such as HTMLButtonElement, and the registration option { extends: "button" }. Support varies by runtime: ECMAScript conformance alone does not provide these DOM APIs, and support for autonomous custom elements does not imply support for customized built-ins.

Examples

<!doctype html>
<meta charset="utf-8">
<title>HTMLElement constructor</title>
<script>
{
  class StatusBadge extends HTMLElement {
    constructor() {
      super();
      this.status = "ready";
    }
  }

  for (const create of [() => new HTMLElement(), () => new StatusBadge()]) {
    try {
      create();
    } catch (error) {
      console.log(error.name);
    }
  }

  customElements.define("cktis-status-badge", StatusBadge);

  for (const badge of [new StatusBadge(), document.createElement("cktis-status-badge")]) {
    console.log(`${badge.localName} ${badge instanceof StatusBadge} ${badge.status} ${badge.isConnected}`);
  }
}
</script>

Result

TypeError
TypeError
cktis-status-badge true ready false
cktis-status-badge true ready false

The first two lines show direct construction failing and subclass construction failing before registration. After registration, both creation paths produce a `StatusBadge` instance with status `ready` that is not yet connected to the document (`false`). Reload the example page in the browser to run it again.

Related lessons

  • JavaScript · Lesson 38 · Intermediate · Version: 3
  • JavaScript · Lesson 39 · Intermediate · Version: 3

Sources