CKTIS / JavaScript
MutationObserver options: mutation types, subtree, filtering, and old values
Configure `observe()` to track child-list, attribute, or character-data changes. Choose how far observation extends and when records should carry the value from before a change.
Version: ECMAScript 2024 and the current web platform; runtime support varies
Syntax
const observer = new MutationObserver((records, observer) => {
for (const record of records) {
// Read record.type, record.target, or record.oldValue.
}
});
observer.observe(target, {
childList: true,
attributes: true,
characterData: true,
subtree: true,
attributeFilter: ["data-state"],
attributeOldValue: true,
characterDataOldValue: true,
});new MutationObserver(callback) creates an observer; observer.observe(target, options) starts watching a DOM node. The callback receives an array of MutationRecord objects and the observer. This is a web DOM API, not part of ECMAScript 2024; availability depends on the runtime.
childList reports direct child nodes added or removed from a watched node (addedNodes, removedNodes). attributes reports attribute additions, changes, and removals on elements. characterData reports edits to an existing CharacterData node, such as changing text.data. Setting an element's textContent replaces its children, so a resulting child-list change is reported as childList, not characterData. subtree: true extends the selected mutation types to descendants; by default, only target is watched.
attributeFilter lists local attribute names, not CSS selectors. With a filter, only listed attributes with no namespace match; without one, all attributes are eligible. attributeOldValue: true and characterDataOldValue: true capture the value before the corresponding mutation in the read-only record.oldValue property. There is no oldValue option or newValue field. oldValue is null for childList, when old-value capture was not requested, or when the attribute did not previously exist.
childList defaults to false. If omitted, attributes becomes true when attributeFilter or attributeOldValue is supplied; characterData becomes true when characterDataOldValue is supplied. Presence counts even if an old-value flag is false. Otherwise both mutation types default to off. observe() throws TypeError if no mutation type is enabled, if attributes: false is combined with a filter or attributeOldValue: true, or if characterData: false is combined with characterDataOldValue: true.
Records reach the callback in batches in a microtask, not during the DOM change itself. With subtree: true, transient registrations can keep a removed descendant's subtree observable. The notification microtask removes those registrations when it processes the observer, before any callback for that batch. Cleanup does not require delivery of a removal record: childList may be off, or takeRecords() may already have drained the queue. disconnect() stops observation and discards pending records; if you need them, call takeRecords() first to drain the queue.
Examples
<!doctype html>
<meta charset="utf-8">
<title>MutationObserver options</title>
<script>
const root = document.createElement("div");
const item = document.createElement("span");
const text = document.createTextNode("before");
item.setAttribute("data-state", "idle");
item.append(text);
root.append(item);
const observer = new MutationObserver((records, self) => {
for (const record of records) {
console.log(JSON.stringify([record.type, record.attributeName, record.oldValue]));
}
self.disconnect();
});
observer.observe(root, {
childList: true,
subtree: true,
attributeFilter: ["data-state"],
attributeOldValue: true,
characterDataOldValue: true,
});
item.setAttribute("data-state", "ready");
item.setAttribute("title", "ignored");
text.data = "after";
item.append(document.createElement("em"));
</script>Result
["attributes","data-state","idle"] ["characterData",null,"before"] ["childList",null,null]
Save the complete example as an `.html` file and open it in a browser. Open the developer console and reload the page. The nodes are never attached to the page. The filter excludes `title`, and the old-value flags enable the omitted `attributes` and `characterData` options. The callback logs three records in mutation order and then stops observing.
Related lessons
- JavaScript · Lesson 31 · Intermediate · Version: 3
Sources
- MutationObserver: observe() method
- MutationObserver: MutationObserver() constructor
- MutationRecord
- MutationRecord: oldValue property
- Node: textContent property
- Using microtasks in JavaScript with queueMicrotask()
- HTML Standard — Event loops
- MutationObserver: disconnect() method
- MutationObserver: takeRecords() method