DOM & EventsBaseline · Widely

Custom Elements Lifecycle and Upgrade Reactions

Mental Model

customElements.define() binds a hyphenated tag name to an HTMLElement subclass. When parsed or upgraded, the engine swaps the node's Prototype Chain and runs deterministic reactions (constructor, attributeChangedCallback, connectedCallback, disconnectedCallback), often paired with Shadow DOM.

Interactive Simulator

Custom Element Upgrade & Reaction Queue

Trace parser upgrade, attributeChangedCallback, and connected/disconnected reactions.

constructor()
attributeChanged
connectedCallback
Step 1 / 3: 1. Element Upgrade (constructor)

customElements.define() upgrades existing <toast-banner> nodes and runs constructor() without touching attributes.

class ToastBanner extends HTMLElement { constructor() { super(); } }
Internal State / Memory
upgraded
true
connected
false

Under the Hood

The HTML parser instantiates unregistered hyphenated tags as HTMLUnknownElement nodes until customElements.define() runs an upgrade pass, swizzling each node's prototype and queuing its reactions. Only when the element is inserted into a connected document does connectedCallback() fire to wire listeners and external state.

  1. Pre-Upgrade State: Unregistered <my-el> tags render as HTMLUnknownElement until define() runs and swizzles their prototype.
  2. Restricted constructor(): The spec forbids reading or mutating attributes or light-DOM children inside constructor(); attach ShadowRoot there and defer DOM setup to connectedCallback().
  3. Move Re-Fires: Moving an element via append() fires disconnectedCallback() then connectedCallback() (unless moveBefore() is used).
JS
class ToastBanner extends HTMLElement {
  static observedAttributes = ['open'];
  #ctrl;
  connectedCallback() {
    this.#ctrl = new AbortController();
    window.addEventListener('keydown', (e) => {
      if (e.key === 'Escape') this.removeAttribute('open');
    }, { signal: this.#ctrl.signal });
  }
  disconnectedCallback() { this.#ctrl?.abort(); }
}
customElements.define('toast-banner', ToastBanner);

Problem Genealogy

  • 2014 (Custom Elements v0): Non-standard document.registerElement with createdCallback failed cross-browser consensus.
  • 2016 (Custom Elements v1): Standardized ES6 class inheritance (extends HTMLElement) and observedAttributes.
  • 2024 (ElementInternals & Form-Associated): Enabled custom elements to participate natively in <form> validation and ARIA.

Production Pitfalls

Production Pitfall
  • DOM Mutations in constructor(): Calling this.setAttribute() in constructor() throws NotSupportedError during HTML parsing.
  • Safari Built-in Rejection: Extending <button is="my-btn"> (extends: 'button') is unsupported in Safari; always use autonomous tags.
When Not to Use
  • When not to use Custom Elements: Avoid wrapping every leaf UI primitive in a custom element if your app already compiles single-framework SSR templates, use them for cross-framework widgets or design-system leaves.

Connections & Logical Next Steps

DOM & EventsCustom Elements Lifecycle and Upgrade Reactions
What This Unlocks
Leaf concept

Mechanical Comparisons