Mutation Observer

HTML5 Mutation Observer API Overview

The HTML5 Mutation Observer API allows JavaScript to watch for changes in the DOM. It can detect when elements are added, removed, updated, or when attributes and text content change. It replaces older mutation events with a more efficient and asynchronous observer-based API.

Mutation Observer is commonly used in dynamic web applications, design systems, analytics, browser extensions, accessibility tooling, custom components, DOM monitoring, third-party widget integration, and applications that need to react when page content changes.

Basic Mutation Observer Example

// HTML5 Mutation Observer API

const target =
  document.querySelector("#app");

const observer =
  new MutationObserver((mutations) => {
    mutations.forEach((mutation) => {
      console.log("Mutation type:", mutation.type);
    });
  });

observer.observe(
  target,
  {
    childList: true,
    subtree: true
  }
);

This example observes the #app element and detects when child elements are added or removed inside it.

How Mutation Observer Works

Mutation Observer watches a target element and sends a list of mutation records to a callback whenever configured DOM changes occur.

Mutation Observer Options

const options =
  {
    childList: true,
    attributes: true,
    characterData: true,
    subtree: true,
    attributeOldValue: true,
    characterDataOldValue: true
  }

observer.observe(
  target,
  options
);

MutationRecord Properties

Watch Added and Removed Elements

const list =
  document.querySelector("#todoList");

const observer =
  new MutationObserver((mutations) => {
    mutations.forEach((mutation) => {
      mutation.addedNodes.forEach((node) => {
        if (node.nodeType === Node.ELEMENT_NODE) {
          console.log("Added:", node.textContent);
        }
      });

      mutation.removedNodes.forEach((node) => {
        if (node.nodeType === Node.ELEMENT_NODE) {
          console.log("Removed:", node.textContent);
        }
      });
    });
  });

observer.observe(
  list,
  {
    childList: true
  }
);

This example detects when list items are added or removed from a to-do list.

Watch Attribute Changes

const button =
  document.querySelector("#saveButton");

const observer =
  new MutationObserver((mutations) => {
    mutations.forEach((mutation) => {
      console.log(
        "Changed attribute:",
        mutation.attributeName
      );

      console.log(
        "Old value:",
        mutation.oldValue
      );

      console.log(
        "New value:",
        mutation.target.getAttribute(
          mutation.attributeName
        )
      );
    });
  });

observer.observe(
  button,
  {
    attributes: true,
    attributeOldValue: true,
    attributeFilter: ["disabled", "aria-expanded", "class"]
  }
);

Attribute observation is useful for monitoring UI state changes such as disabled buttons, expanded menus, selected tabs, theme classes, and ARIA attributes.

Watch Text Changes

const status =
  document.querySelector("#status");

const observer =
  new MutationObserver((mutations) => {
    mutations.forEach((mutation) => {
      console.log(
        "Old text:",
        mutation.oldValue
      );

      console.log(
        "New text:",
        mutation.target.textContent
      );
    });
  });

observer.observe(
  status.firstChild,
  {
    characterData: true,
    characterDataOldValue: true
  }
);

This example watches a text node for changes. It is useful for live status messages, counters, notification labels, and dynamic text updates.

Observe an Entire Subtree

const app =
  document.querySelector("#app");

const observer =
  new MutationObserver((mutations) => {
    mutations.forEach((mutation) => {
      console.log(
        "Change detected:",
        mutation.type
      );
    });
  });

observer.observe(
  app,
  {
    childList: true,
    attributes: true,
    subtree: true
  }
);

The subtree option watches the target and all nested descendants. Use it carefully because observing large DOM trees can affect performance.

Detect Third-Party Widget Changes

const widgetContainer =
  document.querySelector("#widget-container");

const observer =
  new MutationObserver((mutations) => {
    mutations.forEach((mutation) => {
      mutation.addedNodes.forEach((node) => {
        if (
          node.nodeType === Node.ELEMENT_NODE &&
          node.matches(".third-party-widget")
        ) {
          console.log("Widget loaded.");
          node.classList.add("widget-ready");
        }
      });
    });
  });

observer.observe(
  widgetContainer,
  {
    childList: true,
    subtree: true
  }
);

Mutation Observer can detect when third-party scripts inject content into a page and then apply custom logic or styles.

Accessibility Audit Example

const observer =
  new MutationObserver((mutations) => {
    mutations.forEach((mutation) => {
      mutation.addedNodes.forEach((node) => {
        if (
          node.nodeType === Node.ELEMENT_NODE &&
          node.matches("img:not([alt])")
        ) {
          console.warn(
            "Image missing alt text:",
            node
          );
        }
      });
    });
  });

observer.observe(
  document.body,
  {
    childList: true,
    subtree: true
  }
);

Development tools and accessibility helpers can use Mutation Observer to detect accessibility issues in dynamically inserted content.

Mutation Observer Methods

Stop Observing Changes

// Stop observing when done

observer.disconnect();

Use disconnect() when the observer is no longer needed, such as when a component unmounts or a modal closes.

Common Mutation Observer Use Cases

Mutation Observer Best Practices

• Observe the smallest possible DOM subtree.
• Use attributeFilter when watching attributes.
• Disconnect observers when no longer needed.
• Avoid heavy work inside the observer callback.
• Batch or debounce expensive updates.
• Use subtree carefully on large pages.
• Validate node types before using DOM methods.
• Prefer framework lifecycle hooks when working inside React, Vue, or Angular.

Common Mutation Observer Mistakes

• Observing the entire document when a smaller container is enough.
• Forgetting to call disconnect().
• Running expensive DOM queries for every mutation.
• Watching attributes without using attributeFilter.
• Creating infinite loops by changing the same DOM being observed.
• Assuming every added node is an element node.
• Using Mutation Observer when a simple event listener is enough.
• Using it instead of framework lifecycle methods unnecessarily.

Mutation Observer vs Intersection Observer vs Resize Observer

Key Takeaways

• The Mutation Observer API watches DOM changes.
• Use new MutationObserver() to create an observer.
• Use observe() with options to start watching a target.
• Use disconnect() to stop observing and avoid memory leaks.
• Mutation records describe what changed in the DOM.
• Use it carefully because observing large DOM trees can impact performance.