Catching DOM Changes You Didn't Make: MutationObserver in Practice

A client's live-chat widget kept injecting itself above our cookie banner, breaking the layout on mobile. We couldn't edit the widget's code, and it loaded at an unpredictable moment. The fix was to stop chasing their timing and start watching the DOM itself.

const observer = new MutationObserver((mutations) => {
    for (const mutation of mutations) {
        for (const node of mutation.addedNodes) {
            if (node.nodeType === 1 && node.matches?.('.chat-widget')) {
                document.body.append(node);        // move it where we want it
                node.style.zIndex = '30';          // and behave
            }
        }
    }
});

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

The observer fires whenever children change anywhere under body, hands you exactly which nodes appeared, and lets you correct things within the same frame - before the user sees anything jump.

The config options actually matter

observer.observe(target, {
    childList: true,       // nodes added/removed
    subtree: true,         // ...anywhere underneath, not just direct children
    attributes: true,      // attribute changes
    attributeFilter: ['class', 'style'],   // ...but only these
    attributeOldValue: true,               // include the previous value
    characterData: true,   // text node edits
});

The single most important line for performance is attributeFilter. Watching all attributes on a busy subtree (anything with animations, for example) can flood you with thousands of callbacks. Filter to what you care about, and observe the narrowest element that works - body + subtree is the nuclear option, not the default.

Debugging superpower: who keeps changing this element?

Some style keeps flipping and you don't know which script does it? Watch it with attributeOldValue and log a stack trace:

new MutationObserver((muts) => {
    console.trace('style changed:', muts[0].oldValue, '->', muts[0].target.style.cssText);
}).observe(el, { attributes: true, attributeFilter: ['style'], attributeOldValue: true });

The trace points at the guilty code. (DevTools' "Break on attribute modifications" does something similar with a right-click on the element, but the observer version works when you can't sit at a breakpoint - and pairs well with the console tricks I lean on daily.)

Rules I follow

• Callbacks are batched into a microtask, so you never observe mid-mutation - but don't mutate inside the callback carelessly or you'll trigger yourself. Guard against loops.
• Call disconnect() when the component unmounts. Observers keep references alive.
• Don't use it where an event exists. Form inputs fire input events; you don't need to observe value attributes.

MutationObserver is the tool of last resort - and when a third-party script is the problem, last resorts are exactly what you need.