Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / JavaScript

MutationRecord: how to read a DOM change

Identify what changed and which node was affected, inspect added or removed children, and tell when a record contains the previous value.

Version: ECMAScript 2024 and the current web platform; runtime support varies

Syntax

const { type, target, addedNodes, removedNodes, attributeName, oldValue } = record;

A MutationRecord describes one DOM change. A MutationObserver delivers records to its callback in a microtask, not during the change itself. The properties in MutationRecord.type/target/addedNodes/removedNodes/attributeName/oldValue are read-only. Start with type to interpret the other fields. This is a web platform API, not part of ECMAScript 2024; do not assume it is available in a runtime without the DOM.

For type === "childList", target is the node whose direct children changed. addedNodes and removedNodes are NodeList objects containing the children added and removed by that change, respectively. When nothing was added or removed, the corresponding list is empty, not null. Moving a node can produce separate removal and addition records.

For type === "attributes", target is the changed element. attributeName is the attribute's local name, without a namespace prefix. oldValue holds the previous attribute value as a string if observe() was configured with attributeOldValue: true. Otherwise it is null, as it also is when the attribute did not previously exist.

For type === "characterData", target is the CharacterData node itself, such as a text node, not its parent. oldValue holds the previous data as a string only with characterDataOldValue: true; otherwise it is null. For "childList", oldValue is always null. Outside "attributes", attributeName is null, and outside "childList", both node lists are empty.

With subtree: true, the record's target can be a descendant of the node passed to observe(). There is no newValue field: reading from target gives you the current state, which may already reflect later changes.

Examples

<!doctype html>
<meta charset="utf-8">
<title>MutationRecord example</title>
<script>
(() => {
  const root = document.createElement("div");
  const text = document.createTextNode("hello");
  const child = document.createElement("span");
  root.setAttribute("data-state", "before");
  root.append(text);

  const observer = new MutationObserver(() => {});
  observer.observe(root, {
    attributes: true,
    attributeOldValue: true,
    characterData: true,
    characterDataOldValue: true,
    childList: true,
    subtree: true,
  });

  root.setAttribute("data-state", "after");
  text.data = "world";
  root.append(child);
  child.remove();

  const records = observer.takeRecords();
  observer.disconnect();
  const nodeNames = (nodes) => Array.from(nodes, (node) => node.nodeName);
  for (const { type, target, addedNodes, removedNodes, attributeName, oldValue } of records) {
    console.log(JSON.stringify([
      type, target.nodeName, nodeNames(addedNodes), nodeNames(removedNodes),
      attributeName, oldValue,
    ]));
  }
})();
</script>

Result

["attributes","DIV",[],[],"data-state","before"]
["characterData","#text",[],[],null,"hello"]
["childList","DIV",["SPAN"],[],null,null]
["childList","DIV",[],["SPAN"],null,null]

Save the complete example as an HTML file, open it in a browser, and check the console output. `takeRecords()` retrieves and drains the queue before callback delivery, so the code prints four records in order. The addition record still lists `SPAN` even though the node was later removed.

Related lessons

  • JavaScript · Lesson 31 · Intermediate · Version: 3

Sources