Skip to content
Tutorials Center
My learning

Topics

JavaScript Reference ยท DOM: Document and Elements

The MutationObserver interface

Reference for MutationObserver: observe() options, MutationRecord fields, batching in microtasks, takeRecords(), disconnect() and common pitfalls with live examples.

A MutationObserver calls your function whenever the part of the DOM you are watching changes: children added or removed, attributes changed, or text edited. It is the right tool when some other script, a library or the user (with contenteditable) modifies the page and you need to react.

Callbacks are not called synchronously for each change. The browser collects changes and delivers them as a batch of MutationRecord objects shortly after the current script finishes, in a microtask.

JavaScript
const observer = new MutationObserver((records) => {
  console.log(records.length, "mutations");
});
observer.observe(element, { childList: true });

Try it

Watch a list
Changes arrive as one batch

Syntax

JavaScript
const observer = new MutationObserver(callback);
observer.observe(target, options);
observer.disconnect();
const pending = observer.takeRecords();

Parameters

Name Description
callback(records, observer) Receives an array of MutationRecord objects and the observer itself.
target The node to watch (an element, the document, a fragment or a shadow root).
options.childList true to report added and removed child nodes.
options.attributes true to report attribute changes (implied if attributeFilter or attributeOldValue is set).
options.attributeFilter Array of attribute names to watch.
options.attributeOldValue Record the previous attribute value in oldValue.
options.characterData true to report text node changes.
options.characterDataOldValue Record the previous text in oldValue.
options.subtree Also watch all descendants of target.

MutationRecord fields

type ("childList", "attributes" or "characterData"), target, addedNodes, removedNodes, previousSibling, nextSibling, attributeName, attributeNamespace and oldValue.

Return value and exceptions

observe() returns undefined. It throws a TypeError if none of childList, attributes or characterData is enabled. takeRecords() returns the queued records and empties the queue.

Usage notes

  • At least one kind of change must be requested. observe(el, { subtree: true }) alone throws.
  • Changes are batched. Several edits in one script produce one callback with several records. The callback runs in a microtask, after your script but before the browser paints.
  • Avoid feedback loops. If your callback changes what it observes, it triggers itself. Call disconnect() first, make the change, then observe again, or guard with a check.
  • subtree can be expensive. Observing document.body with subtree: true and attributes: true reports every change on the page. Narrow it with attributeFilter and a small target.
  • Removed nodes are still readable in removedNodes, so you can clean up resources tied to them.
  • Disconnect when done. An observer on a long-lived node keeps running until you call disconnect().
  • Form input values are not attributes. Typing in an input changes the value property, not the attribute, so attribute observers do not see it.
  • It replaces the old Mutation Events (DOMNodeInserted and friends), which are deprecated and slow.

Browser support

MutationObserver is supported in every current browser.