How it works
define() validates the name, then reads prototype.connectedCallback, disconnectedCallback, connectedMoveCallback, adoptedCallback and attributeChangedCallback once, plus the static observedAttributes, formAssociated and disabledFeatures. Methods added to the prototype later are never called; Chrome 156 and Firefox 159 both ignored a connectedCallback assigned after define().
Callbacks don't run at arbitrary times. Each DOM method marked [CEReactions] (setAttribute, append, innerHTML…) pushes an element queue; the reactions it causes are queued there and invoked when the method returns. So el.value = 5; console.log('after') logs attributeChanged before after, while a MutationObserver on the same attribute reports later, in a microtask.
An element's custom element state is "undefined" before its definition exists, "custom" after a successful construction, and "failed" if construction threw; :defined matches every built-in element and every "custom" one. Upgrading an element queues an attributeChangedCallback for each observed attribute already present and a connectedCallback if it's in a document, then runs the constructor, so the queued callbacks run after it. super() returns the existing element instead of creating one.
Creation takes one of two paths:
- Synchronous construction:
createElement() and the main-document parser call new Class() directly, then check the result. Any attribute, child, parent, wrong document or wrong local name fails the check with NotSupportedError. Neither path throws to its caller: the exception is reported and the element becomes an HTMLUnknownElement in the "failed" state.
- Upgrade:
innerHTML, insertAdjacentHTML(), cloning and define() create the element first and construct it later, without those checks. That's why the same bad constructor works with insertAdjacentHTML() and fails with createElement(), which is a good reason to follow the rule rather than test your way around it.
Edge cases
Properties set before the upgrade are the most common bug. A framework or script that does el.user = data while the element is still a plain HTMLElement creates an own data property. After the upgrade, that property shadows the class's accessor:
const card = document.querySelector('user-card'); // not defined yet
card.user = 'Ada';
class UserCard extends HTMLElement {
#user = null;
get user() { return this.#user; }
set user(value) { this.#user = value; /* render */ }
connectedCallback() {
console.log(Object.hasOwn(this, 'user'));
// → true
if (Object.hasOwn(this, 'user')) {
const value = this.user;
delete this.user; // remove the own property
this.user = value; // now the setter runs
}
}
}
customElements.define('user-card', UserCard);
Without the fix the setter never runs, so nothing renders, yet card.user still returns 'Ada', which makes the bug hard to see.
Other cases:
- Parsing order. If the definition exists before the parser reaches
<early-el><span>…</span></early-el>, the parser constructs it, applies attributes (firing attributeChangedCallback) and inserts it, so connectedCallback runs with zero children. Read children lazily, watch slotchange, or define the element after the markup.
- Moves.
parent.append(el) on a connected element is a removal plus an insertion: disconnectedCallback, then connectedCallback. With parent.moveBefore(el, null) and a connectedMoveCallback method, only that method runs, so state like observers and focus survives. moveBefore() and the callback exist in Chrome 133+ and Firefox 144+, not Safari.
- Stale callbacks. The spec warns that a
connectedCallback queued before the element was removed still runs, with isConnected already false. Check isConnected before doing connected-only work.
Real-world scenario
A design system ships <ui-tooltip> and its pages render on the server. The bundle loads late, so for a moment every tooltip is an undefined element. Style ui-tooltip:not(:defined) to avoid a layout jump, accept configuration both as attributes (observedAttributes, reflected through getters and setters) and as properties for rich data, upgrade properties assigned early as shown above, and set up and tear down listeners on document in connectedCallback/disconnectedCallback so moving a tooltip doesn't leak handlers.
Trade-offs
- One global registry. Two libraries defining
ui-button collide: the second define() throws. Scoped registries (new CustomElementRegistry(), passed to attachShadow({ customElementRegistry })) let each shadow root use its own definitions; MDN's data lists them in Chrome 146, Firefox 159 and Safari 26, and both harness browsers resolved a scoped definition while the global registry stayed empty.
- Customized built-ins. The best fit for extending native controls, but Safari doesn't implement them, so there you need a polyfill or an autonomous element wrapping the native one.
- Attributes vs properties. Attributes are strings that work in HTML and server rendering; properties carry objects. Most components reflect primitive state to attributes and keep complex data as properties only.