Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / JavaScript

MutationRecord — a DOM change record

MutationRecord describes one observed DOM change. Learn how to identify its type and affected node, inspect added and removed nodes, and retrieve an attribute name and previous value.

Version: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Syntax

record.type; record.target; record.addedNodes; record.removedNodes; record.attributeName; record.oldValue

MutationRecord is a read-only interface describing a DOM change observed by a MutationObserver. Records arrive in the array passed to the observer callback; pending records can also be retrieved with takeRecords(). This is a DOM API, not part of ECMAScript itself. MDN classifies it as widely available across browsers since July 2015; having Node 24 in a project does not establish support for this browser API.

MutationRecord.type is "attributes", "characterData", or "childList". MutationRecord.target identifies, respectively, the element whose attribute changed, the changed CharacterData node, or the node whose child list changed—not the added or removed child.

MutationRecord.addedNodes and MutationRecord.removedNodes are NodeList objects containing nodes added and removed by that change. Each list is empty when there are no corresponding nodes. MutationRecord.attributeName contains the changed attribute's name for "attributes" and is null for other types.

MutationRecord.oldValue contains the previous attribute value only when attributeOldValue is enabled, or previous CharacterData only when characterDataOldValue is enabled. The corresponding mutation kind must also be observed. Otherwise, including for "childList", it is null; a previously absent attribute can also have an old value of null.

The example observes a detached element and reads records synchronously using takeRecords(), which empties the queue. This avoids waiting for the callback. After retrieving the records, it disconnects the observer.

Examples

(() => {
  const root = document.createElement("div");
  root.setAttribute("data-state", "idle");
  const observer = new MutationObserver(() => {});
  observer.observe(root, {
    attributes: true,
    attributeOldValue: true,
    childList: true
  });

  root.setAttribute("data-state", "ready");
  const child = document.createElement("span");
  root.appendChild(child);
  root.removeChild(child);

  const records = observer.takeRecords();
  observer.disconnect();
  for (const record of records) {
    console.log(JSON.stringify([
      record.type,
      record.target === root,
      record.addedNodes.length,
      record.removedNodes.length,
      record.attributeName,
      record.oldValue
    ]));
  }
})();

Result

["attributes",true,0,0,"data-state","idle"]
["childList",true,1,0,null,null]
["childList",true,0,1,null,null]

The displayed code and declared result were verified in an isolated environment using the method recorded in the verification evidence for this exact version.

Sources