Why does observe() throw on my config?

MutationObserver.observe requires at least one of childList, attributes or characterData to be true. A config with only subtree or only the OldValue flags is invalid because there is nothing concrete to watch, so the call throws a TypeError.

What does the subtree option do?

subtree extends whichever of childList, attributes and characterData you enabled to the target's entire descendant tree, not just its direct children or itself. It is how you watch a whole component or document fragment for any change.

How do I get the previous value of an attribute?

Set attributeOldValue: true (which implies attributes: true). Each MutationRecord then exposes oldValue with the attribute's prior value. Use characterDataOldValue for text nodes in the same way.

When does the callback run?

The callback is queued as a microtask after the current task finishes, receiving a batch of MutationRecord objects. Multiple DOM mutations within one task coalesce into a single callback, which keeps observing cheap.

Does this tool watch the page DOM?

No. It builds and validates an observe() config and documents the record shape. It does not create a real observer, and nothing is uploaded or stored.

MutationObserver Options Reference

Email me this result

Get this tool's output sent to your inbox, plus one useful tool a week. No spam, unsubscribe any time.

Watching the DOM for changes

MutationObserver reports DOM changes — added or removed nodes, attribute edits and text changes — asynchronously and in batches, replacing the deprecated Mutation Events. Its behaviour is driven entirely by the options object passed to observe() and read through the MutationRecord entries in your callback. This reference covers both, with a validator for the must-have-one-of-three rule.

How it works

You create an observer with a callback, then call observe(target, options):

const mo = new MutationObserver((records) => {
  for (const r of records) {
    if (r.type === "childList") console.log(r.addedNodes, r.removedNodes);
    if (r.type === "attributes") console.log(r.attributeName, r.oldValue);
  }
});

mo.observe(node, {
  childList: true,
  attributes: true,
  attributeOldValue: true,
  subtree: true,
});

At least one of childList, attributes or characterData must be true or observe() throws. subtree widens the scope to all descendants, and the *OldValue and attributeFilter flags implicitly turn on their related option. The callback runs as a microtask with a coalesced batch of records.

Tips and notes

A config with only subtree: true is invalid — pair it with at least one concrete flag.
attributeFilter limits noise by reporting only the named attributes you care about.
Disconnect with mo.disconnect() when done, and mo.takeRecords() drains any pending queue.
Beware feedback loops: mutating the DOM inside the callback can re-trigger the observer.