MutationObserver: MutationObserver() constructor
Baseline
Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.
The DOM MutationObserver()
constructor — part of the MutationObserver interface — creates and
returns a new observer which invokes a specified callback when DOM events
occur.
DOM observation does not begin immediately; the
observe() method must be called first to
establish which portion of the DOM to watch and what kinds of changes to watch for.
Syntax
new MutationObserver(callback)
Parameters
callback-
A function which will be called on each DOM change that qualifies given the observed node or subtree and options.
The
callbackfunction takes as input two parameters:- An array of
MutationRecordobjects, describing each change that occurred. - The
MutationObserverwhich invoked thecallback. This is most often used to disconnect the observer usingMutationObserver.disconnect().
See the examples below for more details.
- An array of
Return value
A new MutationObserver object, configured to call the specified
callback when DOM mutations occur.
Examples
Observing child elements
This example has buttons to add an <li> element to a list, and to remove the first <li> element from the list.
We use a MutationObserver to be notified about changes to the list. In the callback, we log additions and removals, and as soon as the list is empty, we disconnect the observer.
The "Reset example" button resets the example to its original state.
HTML
<button id="add">Add child</button>
<button id="remove">Remove child</button>
<button id="reset">Reset example</button>
<ul id="container"></ul>
<pre id="log"></pre>
CSS
#container,
#log {
height: 150px;
overflow: scroll;
}
#container li {
background-color: paleturquoise;
margin: 0.5rem;
}
JavaScript
const add = document.querySelector("#add");
const remove = document.querySelector("#remove");
const reset = document.querySelector("#reset");
const container = document.querySelector("#container");
const log = document.querySelector("#log");
let namePrefix = 0;
add.addEventListener("click", () => {
const newItem = document.createElement("li");
newItem.textContent = `item ${namePrefix}`;
container.appendChild(newItem);
namePrefix++;
});
remove.addEventListener("click", () => {
const itemToRemove = document.querySelector("li");
if (itemToRemove) {
itemToRemove.parentNode.removeChild(itemToRemove);
}
});
reset.addEventListener("click", () => {
document.location.reload();
});
function logChanges(records, observer) {
for (const record of records) {
for (const addedNode of record.addedNodes) {
log.textContent = `Added: ${addedNode.textContent}\n${log.textContent}`;
}
for (const removedNode of record.removedNodes) {
log.textContent = `Removed: ${removedNode.textContent}\n${log.textContent}`;
}
if (record.target.childNodes.length === 0) {
log.textContent = `Disconnected\n${log.textContent}`;
observer.disconnect();
}
console.log(record.target.childNodes.length);
}
}
const observerOptions = {
childList: true,
subtree: true,
};
const observer = new MutationObserver(logChanges);
observer.observe(container, observerOptions);
Result
Try clicking "Add child" to add list items, and "Remove child" to remove them. The observer callback logs additions and removals. As soon as the list is empty, the observer logs a "Disconnected" message and disconnects the observer.
The "Reset example" button reloads the example so you can try it again.
Specifications
| Specification |
|---|
| DOM # ref-for-dom-mutationobserver-mutationobserver① |
Browser compatibility
| desktop | mobile | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
MutationObserver() constructor
|
|
|
|
|
|
|
|
|
|
|
|
|
Legend
Tip: you can click/tap on a cell for more information.
- Full support
- Full support
- Requires a vendor prefix or different name for use.
- Has more compatibility info.