MutationObserver DOM Change Tracking

MutationObserver is the browser's native way of watching the DOM itself change shape — nodes appearing and disappearing, attributes flipping, text being rewritten — without resorting to the deprecated, synchronous Mutation Events. It complements IntersectionObserver and ResizeObserver: where those two track where an element is and how big it is, MutationObserver tracks what changed structurally inside a subtree. This guide covers the full observe() options schema, the MutationRecord shape, batching semantics, configuration variants, and the gotchas that trip up most production implementations.

Concept Framing

Before MutationObserver shipped, developers who needed to react to DOM changes relied on Mutation Events (DOMNodeInserted, DOMSubtreeModified, and friends) — a set of synchronous DOM events fired individually for every single mutation, in the middle of the mutation itself. A script that appended 500 list items could trigger 500 synchronous event dispatches, each one capable of triggering further mutations, each one blocking the thread until every listener returned. Browsers eventually deprecated the entire family because of the performance and reentrancy hazards it created.

MutationObserver replaces that model with asynchronous, batched delivery. Instead of firing your callback once per mutation, the browser accumulates every qualifying mutation that occurs during the current synchronous task into an ordered list of MutationRecord objects, and delivers the entire list to your callback exactly once, in a microtask queued after the current task completes — before the next paint, but after your synchronous JavaScript finishes running. This means a loop that mutates the DOM a thousand times in a row still produces exactly one callback invocation, with a thousand-entry records array.

The diagram below shows three different mutation types occurring synchronously, being buffered into a single queue, and then crossing the microtask boundary together:

Three practical consequences follow from this model. First, your callback must always iterate the records array — never assume exactly one mutation happened. Second, because delivery is deferred to a microtask, the DOM may have changed again by the time your callback runs, so record.target and record.addedNodes reflect the state at the moment of mutation, not necessarily the current state. Third, calling observer.takeRecords() synchronously drains and returns the pending queue without waiting for the microtask — useful immediately before disconnect() to avoid losing a final batch.

Spec / Signature Reference Table

MutationObserver is constructed with a callback, then configured per target through observe(target, options). Every flag in the options object is opt-in — omitting a category means the browser does no extra bookkeeping for it, so scope options tightly.

Every notification arrives as a MutationRecord. The table below covers the fields your callback reads most often:

Step-by-Step Implementation

Step 1 — Guard SSR and create the observer

type MutationHandler = (records: MutationRecord[], observer: MutationObserver) => void;

function createMutationWatcher(handler: MutationHandler): MutationObserver | null {
  // SSR guard — MutationObserver does not exist in Node.js
  if (typeof MutationObserver === 'undefined') return null;
  return new MutationObserver(handler);
}

// Plain JS equivalent
function createMutationWatcher(handler) {
  if (typeof MutationObserver === 'undefined') return null;
  return new MutationObserver(handler);
}

Step 2 — Call observe() with an explicit, narrow options object

Request only what you need. Watching childList and attributes together on a large subtree multiplies the number of records the browser must construct on every keystroke or animation frame that touches the DOM.

interface WatchOptions {
  childList?: boolean;
  attributes?: boolean;
  attributeFilter?: string[];
  attributeOldValue?: boolean;
  characterData?: boolean;
  characterDataOldValue?: boolean;
  subtree?: boolean;
}

function watchContainer(
  target: Node,
  observer: MutationObserver,
  options: WatchOptions
): void {
  observer.observe(target, options);
}

// Watch a list container for added/removed rows and a data-state attribute
const listContainer = document.querySelector<HTMLElement>('#item-list')!;
const watcher = createMutationWatcher(handleListMutations);
watcher?.observe(listContainer, {
  childList: true,
  attributes: true,
  attributeFilter: ['data-state'],
  subtree: false,
});

Step 3 — Branch on record.type inside the callback

function handleListMutations(records: MutationRecord[]): void {
  for (const record of records) {
    switch (record.type) {
      case 'childList':
        record.addedNodes.forEach((node) => {
          if (node.nodeType === Node.ELEMENT_NODE) {
            onRowAdded(node as Element);
          }
        });
        record.removedNodes.forEach((node) => {
          if (node.nodeType === Node.ELEMENT_NODE) {
            onRowRemoved(node as Element);
          }
        });
        break;
      case 'attributes':
        if (record.attributeName === 'data-state') {
          onStateAttributeChanged(record.target as Element, record.oldValue);
        }
        break;
      case 'characterData':
        onTextChanged(record.target as CharacterData, record.oldValue);
        break;
    }
  }
}

Step 4 — Flush pending records before teardown

takeRecords() synchronously returns and clears any records the browser has queued but not yet delivered. Call it immediately before disconnect() if your teardown logic depends on processing a final, in-flight batch (for example, persisting the last known DOM state before a route change unmounts the container).

function teardownWatcher(observer: MutationObserver, handler: MutationHandler): void {
  const pending = observer.takeRecords();
  if (pending.length > 0) handler(pending, observer);
  observer.disconnect();
}

Step 5 — Disconnect in the framework's unmount hook

disconnect() stops the observer and discards any records still queued for delivery that you didn't flush with takeRecords(). Always pair every observe() call with a corresponding disconnect() — see Observer Lifecycle & Memory Management for the retention chains that build up when this is skipped.

// React
useEffect(() => {
  const watcher = createMutationWatcher(handleListMutations);
  watcher?.observe(listRef.current!, { childList: true, subtree: true });
  return () => watcher?.disconnect();
}, []);

Configuration Variants

The options object shape doesn't change, but the combinations you choose define an entirely different observation profile. Pick the narrowest variant that satisfies the use case:

The "full surveillance" variant is the most expensive by a wide margin — every insertion, removal, attribute write, and text edit anywhere below the target produces a record. Reserve it for tooling contexts (editors, diagnostics panels) rather than always-on production UI code.

Edge Cases & Gotchas

subtree: true performance cost

subtree: true is the single biggest lever on record volume. Attaching it to document.body means every mutation anywhere on the page — including ones made by third-party scripts, ad iframes' parent-visible DOM, or unrelated components — gets recorded and delivered to your callback. Scope the observed target to the smallest container that actually needs watching, and prefer re-attaching a fresh, narrowly-scoped observer over widening an existing one.

characterData needs the actual text node

characterData: true only fires for mutations on Text, Comment, and ProcessingInstruction nodes — never on the Element that contains them. If you observe a <div> with characterData: true but not subtree: true, you will never see edits to the text inside it, because the text lives on a child Text node, not on the <div> itself. Pair characterData with subtree: true when observing an element ancestor, or observe the Text node directly if you already have a reference to it.

attributeOldValue and characterDataOldValue are opt-in

MutationRecord.oldValue is null unless you explicitly request it. Passing attributes: true alone gives you the mutation's occurrence and the new attribute name, but not its previous value — you must add attributeOldValue: true as well. The same pairing rule applies to characterData and characterDataOldValue. Forgetting the oldValue flag is the most common reason an undo/redo implementation silently breaks.

Reentrancy — mutating the DOM inside your own callback

Because delivery happens in a microtask after your synchronous code finishes, it's easy to write a callback that mutates the observed subtree (for example, normalizing whitespace or auto-formatting attributes), which schedules another batch of records for the next microtask tick. This is safe as long as your handler is idempotent — it should recognize the state it just produced and not loop indefinitely. A common defensive pattern is toggling a isApplyingFix flag around your own writes and skipping records that match your own signature.

Combining with IntersectionObserver / ResizeObserver for dynamic nodes

MutationObserver is frequently the missing piece when IntersectionObserver or ResizeObserver need to track elements that don't exist yet. Since both of those observers only report on elements you've explicitly called observe() on, a container that receives new children at runtime (infinite scroll, dynamically rendered widgets) needs a childList watcher to detect the new node and call intersectionObserver.observe(newNode) on it — and, symmetrically, to call unobserve()/cleanup when the node is removed. The detecting added and removed nodes with MutationObserver guide walks through this exact bridging pattern in full.

When NOT to use MutationObserver

MutationObserver reports DOM structure, attributes, and character data — nothing about rendered geometry. It will not fire when an element's visual size changes due to CSS (flex reflow, font loading, media queries) without a corresponding attribute mutation; use ResizeObserver for that. It will not fire on scroll-driven visibility changes; use IntersectionObserver. And it is a poor substitute for framework-level reactivity — if you're already inside React, Vue, or Angular and control the render path, prefer the framework's own change-detection or effect system over polling the rendered DOM with a mutation watcher.

Framework Integration Patterns

React — a typed hook

import { useEffect, useRef } from 'react';

function useMutationObserver(
  target: React.RefObject<Element>,
  options: MutationObserverInit,
  callback: MutationCallback
): void {
  useEffect(() => {
    if (!target.current || typeof MutationObserver === 'undefined') return;
    const observer = new MutationObserver(callback);
    observer.observe(target.current, options);
    return () => observer.disconnect();
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [target.current]);
}

Vue 3 — a composable

import { onMounted, onUnmounted, Ref } from 'vue';

export function useMutationWatcher(
  targetRef: Ref<Element | null>,
  options: MutationObserverInit,
  callback: MutationCallback
): void {
  let observer: MutationObserver | null = null;

  onMounted(() => {
    if (!targetRef.value || typeof MutationObserver === 'undefined') return;
    observer = new MutationObserver(callback);
    observer.observe(targetRef.value, options);
  });

  onUnmounted(() => observer?.disconnect());
}

Angular — a directive

import { Directive, ElementRef, Input, OnDestroy, OnInit } from '@angular/core';

@Directive({ selector: '[appMutationWatch]', standalone: true })
export class MutationWatchDirective implements OnInit, OnDestroy {
  @Input() appMutationWatchOptions: MutationObserverInit = { childList: true };
  private observer: MutationObserver | null = null;

  constructor(private el: ElementRef<Element>) {}

  ngOnInit(): void {
    this.observer = new MutationObserver((records) => this.handleRecords(records));
    this.observer.observe(this.el.nativeElement, this.appMutationWatchOptions);
  }

  private handleRecords(records: MutationRecord[]): void {
    records.forEach((record) => {
      if (record.type === 'childList') {
        // react to added/removed nodes
      }
    });
  }

  ngOnDestroy(): void {
    this.observer?.disconnect();
  }
}

Debugging Checklist

Callback never fires:

• Confirm at least one of childList, attributes, or characterData is set to true in the options passed to observe() — an empty options object throws a TypeError in some engines and silently does nothing in others.
• If watching text edits, confirm subtree: true is set when the target is an ancestor Element rather than the Text node itself.
• Check that observe() was called on a node still attached to the document at call time — mutations on a detached subtree that is later attached elsewhere are still tracked, but a target replaced entirely (rather than mutated) severs the observation.

Missing oldValue:

• Verify attributeOldValue: true (for attributes) or characterDataOldValue: true (for text) was passed explicitly — these are never inferred from attributes/characterData alone.

Records arriving later than expected:

• Remember delivery is microtask-scheduled after the current synchronous task. If you need the pending batch immediately (e.g., right before disconnect()), call takeRecords() rather than waiting for the callback.

Too many records / performance regressions:

• Audit for subtree: true attached to a large or high-churn container. Narrow the target, or split one wide observer into several narrowly-scoped ones only where needed.
• Check attributeFilter is set when only specific attributes matter — omitting it means every attribute write on the target generates a record, including ones set by browser extensions or third-party scripts.

Reproduction script:

// Paste in DevTools console to inspect live mutation records
const debugObserver = new MutationObserver((records) => {
  console.table(records.map((r) => ({
    type: r.type,
    target: (r.target as Element).tagName ?? r.target.nodeName,
    added: r.addedNodes.length,
    removed: r.removedNodes.length,
    attribute: r.attributeName,
    oldValue: r.oldValue,
  })));
});
debugObserver.observe(document.querySelector('#your-container')!, {
  childList: true,
  attributes: true,
  attributeOldValue: true,
  characterData: true,
  characterDataOldValue: true,
  subtree: true,
});

Chrome DevTools also exposes a built-in alternative for one-off inspection: right-click any element in the Elements panel and choose Break on → Subtree modifications, Attribute modifications, or Node removal to pause script execution the instant a matching mutation occurs, without writing any observer code at all.

Frequently Asked Questions

Related

• Detecting Added and Removed Nodes with MutationObserver
• IntersectionObserver API Deep Dive
• ResizeObserver Mechanics & Triggers
• Observer Lifecycle & Memory Management
• Browser Compatibility & Polyfills

↑ Back to Core Observer Fundamentals & Browser APIs