Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / JavaScript

MutationObserver — observing DOM changes

MutationObserver records selected DOM changes and delivers records asynchronously to a callback. Learn how observe() configures observation, takeRecords() drains the queue, and disconnect() stops observation.

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

const observer = new MutationObserver((records, observer) => { /* handle records */ });
observer.observe(target, options);
const pending = observer.takeRecords();
observer.disconnect();

MutationObserver is a DOM-standard API, not part of ECMAScript itself. Its callback receives an array of MutationRecord objects and the observer. Notification is queued as a microtask, not delivered synchronously during a change; one invocation can contain multiple records. Having Node 24 in a repository does not establish availability of this browser API.

MutationObserver.observe, called as observer.observe(target, options), selects a node and mutation types: childList tracks added and removed children, attributes tracks attributes, and characterData tracks text-node and similar data. subtree: true includes descendants. At least one type must be enabled after defaults apply; otherwise a TypeError is thrown. attributeFilter restricts attribute names; attributeOldValue and characterDataOldValue request previous values. Attribute- or data-related options can implicitly enable their corresponding observation type, but explicitly conflicting settings throw TypeError.

MutationObserver.takeRecords, called as observer.takeRecords(), synchronously returns pending records and empties the queue without invoking the callback or stopping observation. MutationObserver.disconnect, called as observer.disconnect(), stops all observations for this object and discards pending records. Retrieve them first if needed. The object can be restarted using observe().

The example observes a detached element, retrieves its record before notification delivery, and stops observation. oldValue is null because the attribute did not previously exist. Keep observation narrowly scoped; mutations made by the callback can produce further notifications.

Examples

{
  const target = document.createElement('div');
  const observer = new MutationObserver((records) => {
    console.log('callback:', records.length);
  });

  observer.observe(target, {
    attributes: true,
    attributeFilter: ['data-state'],
    attributeOldValue: true
  });

  target.setAttribute('data-state', 'ready');
  const records = observer.takeRecords();
  console.log(JSON.stringify(records.map((record) => ({
    type: record.type,
    attributeName: record.attributeName,
    oldValue: record.oldValue
  }))));

  observer.disconnect();
  target.setAttribute('data-state', 'done');
  console.log(observer.takeRecords().length);
}

Result

[{"type":"attributes","attributeName":"data-state","oldValue":null}]
0

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