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.
const observer = new MutationObserver((records) => { console.log(records.length, "mutations"); }); observer.observe(element, { childList: true });
Try it
Syntax
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. subtreecan be expensive. Observingdocument.bodywithsubtree: trueandattributes: truereports every change on the page. Narrow it withattributeFilterand 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
valueproperty, not the attribute, so attribute observers do not see it. - It replaces the old Mutation Events (
DOMNodeInsertedand friends), which are deprecated and slow.
Browser support
MutationObserver is supported in every current browser.