Custom Elements Lifecycle and Upgrade Reactions
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.
Custom Element Upgrade & Reaction Queue
Trace parser upgrade, attributeChangedCallback, and connected/disconnected reactions.
customElements.define() upgrades existing <toast-banner> nodes and runs constructor() without touching attributes.
class ToastBanner extends HTMLElement { constructor() { super(); } }- 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.
- Pre-Upgrade State: Unregistered
<my-el>tags render asHTMLUnknownElementuntildefine()runs and swizzles their prototype. - Restricted
constructor(): The spec forbids reading or mutating attributes or light-DOM children insideconstructor(); attachShadowRootthere and defer DOM setup toconnectedCallback(). - Move Re-Fires: Moving an element via
append()firesdisconnectedCallback()thenconnectedCallback()(unlessmoveBefore()is used).
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.registerElementwithcreatedCallbackfailed cross-browser consensus. - 2016 (Custom Elements v1): Standardized ES6 class inheritance (
extends HTMLElement) andobservedAttributes. - 2024 (
ElementInternals& Form-Associated): Enabled custom elements to participate natively in<form>validation and ARIA.
Production Pitfalls
- DOM Mutations in
constructor(): Callingthis.setAttribute()inconstructor()throwsNotSupportedErrorduring 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 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
Custom elements typically attach a ShadowRoot in constructor() and hydrate slots in connectedCallback().
Element upgrades swizzle the DOM node's [[Prototype]] to the registered HTMLElement subclass.
Native elements expose built-in ARIA semantics, whereas autonomous custom elements require ElementInternals to wire roles.