Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 39 ยท Custom Elements

Custom Element Lifecycle Callbacks

Learn every custom element lifecycle callback: constructor, connectedCallback, disconnectedCallback, attributeChangedCallback, adoptedCallback, and how to clean up.

A custom element lives through several moments: it is created, added to a page, changed, moved, removed. The browser tells your class about each moment by calling special methods named lifecycle callbacks. Knowing when each callback fires and what you may safely do in it is the key to writing components that neither leak memory nor break when elements move around.

The callbacks at a glance

Callback When the browser calls it
constructor() The element is created or upgraded
connectedCallback() The element is inserted into a document
disconnectedCallback() The element is removed from a document
attributeChangedCallback(name, oldValue, newValue) An observed attribute is added, changed or removed
adoptedCallback(oldDocument, newDocument) The element is moved to a different document
flowchart LR
  A["constructor"] --> B["attributeChangedCallback (initial attributes)"]
  B --> C["connectedCallback"]
  C --> D["attributeChangedCallback (updates)"]
  D --> E["disconnectedCallback"]
  E -->|"re-inserted"| C

The same element can be connected and disconnected many times, so these callbacks can fire repeatedly.

Watching it happen

The easiest way to learn is to log every callback and then poke the element.

Lifecycle logger

Press the buttons in order and read the console. Creating the element logs constructor; setting level before insertion logs attributeChangedCallback; appending logs connectedCallback. Moving it with append to another parent logs a disconnectedCallback followed by a connectedCallback, because a move is a remove plus an insert.

constructor

Covered in the previous lesson: set up fields and the shadow root, nothing else. Do not touch attributes or children.

connectedCallback

This is the main setup hook. The element is in the DOM, so you can read attributes, read children, measure layout, start timers and subscribe to events. Two cautions:

  • It can run more than once (every time the element is inserted), so guard one-time work, or make setup idempotent.
  • When the parser creates the element, the callback may run before the element's children have been parsed. If you must read light DOM children that appear in the HTML source, wait for them with a MutationObserver or use slotchange (see the slots chapter), or load your script with type="module" or defer so the full document is already parsed.

disconnectedCallback

The mirror image. Use it to undo whatever connectedCallback started: clear intervals, abort fetches, remove global listeners and disconnect observers. Skipping this is the most common source of memory leaks in components.

Clean up in disconnectedCallback

Without clearInterval, the interval would keep firing against a detached element forever.

attributeChangedCallback

Fires for each attribute listed in the static observedAttributes array, including the initial attributes set by the parser (before connectedCallback). The next lesson explores this in depth.

adoptedCallback

Called when document.adoptNode() or importNode moves the element into another document, for example between the main page and an iframe. It is rare. A typical use is updating references to the old ownerDocument.

The order for parsed HTML

For an element already present in the HTML, when the definition runs (an upgrade), the order is:

  1. constructor
  2. attributeChangedCallback once for each observed attribute that exists
  3. connectedCallback

For document.createElement, the order follows your own code: constructor, then whatever attribute changes you make, then connectedCallback when you append.

Quick rules of thumb

  • Setup in connectedCallback, teardown in disconnectedCallback.
  • Make both safe to repeat. An element may be moved around.
  • Render once, then update. Create the shadow tree the first time, and only update pieces later.
  • Do not assume attribute order. Callbacks arrive one attribute at a time.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which callback should you use to start a timer for a component?

    connectedCallback runs when the element is in the page. Pair it with disconnectedCallback to stop the timer.
  2. 2. What happens when you move an element with parent.append(el) from another parent?

    A move is a removal and an insertion, so both callbacks fire.
  3. 3. Why should disconnectedCallback exist in a component that uses setInterval?

    Intervals keep running until cleared, even if the element is no longer in the document.
  4. 4. For which attributes is attributeChangedCallback called?

    The browser only reports changes to attributes you list in observedAttributes.

Summary

  • The five callbacks are constructor, connectedCallback, disconnectedCallback, attributeChangedCallback and adoptedCallback.
  • Start work in connectedCallback and stop it in disconnectedCallback.
  • A move triggers both disconnect and connect, so make them repeatable.
  • Observed attributes fire attributeChangedCallback, including the initial ones.
  • Do not rely on children being parsed when connectedCallback runs from parsed HTML.

Next: Attributes and observedAttributes