Stop 06 · Browser APIsTopics · 6/13

Mutation Observer

In short

Sometimes the page changes and you didn't change it: a third-party widget adds elements, or a library edits classes. Mutation Observer tells you when the DOM changes.

An API that watches a DOM subtree and fires a callback when nodes, attributes or text content change — useful for reacting to DOM changes made outside your own code. It is particularly useful at integration boundaries where another library, browser feature, or third-party script changes DOM content your code needs to observe.

The jaadu mascot behind a shop counter watches a CCTV camera as someone moves a box on a shelf.

Think of it like this

CCTV in the kirana store

The shop owner can't watch every shelf all day. The CCTV records whenever something is added, removed or moved, and he checks the clips in a batch. Mutation Observer is CCTV for a part of your page.

Watch it happen

A new chat message arrives

Chat widget

#chat-messages

Observer

Your callback

observe(childList)

1/5You start watching the chat box, but only for children being added or removed.

The big ideas

What you need to know

Reports DOM changes

It can notice added or removed child elements, changed attributes and changed text.

You choose what to watch

Pass options like childList, attributes and subtree. Watch only what you need.

Changes come in batches

Many quick changes are grouped and delivered together, not one callback per tiny edit.

disconnect when done

Call observer.disconnect() so it stops watching and doesn't waste memory.

See it in code

Walk through the code

1const chat = document.querySelector("#chat-messages");2 3const observer = new MutationObserver((mutations) => {4  for (const m of mutations) {5    if (m.type === "childList" && m.addedNodes.length > 0) {6      chat.scrollTop = chat.scrollHeight; // stick to newest message7    }8  }9});10 11observer.observe(chat, { childList: true });12 13// Later, e.g. when the chat closes14// observer.disconnect();

1/4The callback receives a batch of mutation records and loops through them.

Whatever code adds a message, the chat scrolls to the bottom. The observer doesn't care who made the change.

Save yourself the pain

Common mistakes

Oops

Observing document.body with subtree: true and every option turned on.

Do this instead

Watch the smallest element you can, with only the options you need. Otherwise the callback fires constantly.

Oops

Changing the same element inside the callback and creating an endless loop.

Do this instead

Check before you change, or disconnect while you edit and observe again after.

Your mission

Spot the changes

~20 min

Quick check

You observe an element with only { attributes: true }. A child element is added. What happens?

Go deeper

1Watch a container element and log whenever children are added or removed. Validate your understanding by applying it in a small practical example.
2Compare this to React's own re-render model — you rarely need it in React apps directly. Write down when you would choose each option and what trade-off drives that choice.
3Learn a realistic use case: detecting when a third-party script injects DOM content.