MutationObserver API

TL;DR

Explanation

MutationObserver fires when the observed DOM subtree changes. Config options: childList (child add/remove), attributes (attribute changes), subtree (observe all descendants), characterData (text changes), attributeFilter (specific attributes). Each callback receives MutationRecord[] with type, target, addedNodes, removedNodes, attributeName, oldValue. Use cases: third-party content monitoring, auto-initializing widgets on dynamic HTML, form auto-save on change. Performance: batches mutations and calls callback asynchronously. Alternative to legacy DOMSubtreeModified event.

Common Misconception

Why It Matters

Common Mistakes

• Not disconnecting on cleanup — observes forever.
• Infinite loops: modifying the DOM inside the callback triggers the observer again.
• Observing document.body with subtree:true — very expensive on large pages.

Code Examples

// Polling instead of observing:
setInterval(() => {
    if (document.querySelector('.new-content')) {
        initWidget();
    }
}, 100);

const observer = new MutationObserver(mutations => {
    for (const mutation of mutations) {
        for (const node of mutation.addedNodes) {
            if (node.classList?.contains('widget')) initWidget(node);
        }
    }
});
observer.observe(document.body, { childList: true, subtree: true });
// Cleanup: observer.disconnect();

References

• ↗ https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver

Tags

Related Terms