MutationObserver

## What observe() actually registers A `MutationObserver` is created with a callback and watches nothing until you register it: ```js const mo = new MutationObserver((records, observer) => { /* ... */ }); mo.observe(el, { childList: true }); ``` `observe(target, options)` creates a registration on `target` that says which *categories* of change should produce `MutationRecord` objects. The options object is a whitelist: every category you do not name is off. One observer may register on many nodes; every record from every registration arrives at the same callback, and you tell them apart with `record.type` and `record.target`. ## The three categories **`childList`** — child nodes of the observed node being inserted or removed. That covers `append`, `prepend`, `remove`, `replaceChildren`, `insertBefore`, and assignments to `innerHTML` or `textContent` (which remove the old children and insert new ones). The record carries `addedNodes`, `removedNodes`, `previousSibling` and `nextSibling`, with `target` set to the parent whose child list changed. **`attributes`** — an attribute set or removed on an observed element. The record carries `attributeName` and `attributeNamespace`, with `target` set to the element. Note that the record tells you *which* attribute changed, not the new value — you read that back off `target` yourself. **`characterData`** — the data of a `CharacterData` node (a `Text` or `Comment` node) changing in place, as in `node.data = 'x'`. The record's `target` is the text node itself, not its parent element. ## subtree widens whatever you enabled `subtree: true` is a modifier, not a category. It means "apply the categories I enabled to this node and every descendant". `{ childList: true, subtree: true }` therefore reports insertions and removals anywhere below the target, with `target` naming the specific parent involved. `{ subtree: true }` alone still enables nothing, which is why it throws. ## At least one category is mandatory The DOM specification requires that `childList`, `attributes` or `characterData` be true, and `observe()` throws a `TypeError` otherwise. Two conveniences soften that rule: if you pass `attributeOldValue` or `attributeFilter` without mentioning `attributes`, `attributes` is treated as true; likewise `characterDataOldValue` implies `characterData`. But explicitly combining `attributes: false` with `attributeFilter`, or `characterData: false` with `characterDataOldValue`, is a `TypeError` — the spec refuses contradictory options rather than guessing. ## The text-node trap The most common surprise is observing an element for text changes: ```js mo.observe(p, { characterData: true }); // never fires p.firstChild.data = 'updated'; ``` The mutation happens on the `Text` node, which is a *child* of `p`, so the registration on `p` does not cover it. Either observe the text node directly, or use `{ characterData: true, subtree: true }` on `p`. Confusingly, `p.textContent = 'updated'` *does* fire an observer with `{ childList: true }`, because that assignment replaces the child text node rather than editing it — same visible outcome, different mutation category. ## Re-registering and stacking options Calling `observe()` a second time for the same node with the same observer does not add a second registration: it **replaces** the options for that node. So this is a bug: ```js mo.observe(el, { childList: true }); mo.observe(el, { attributes: true }); // childList is now OFF for el ``` If you want both, ask for both in one call: `mo.observe(el, { childList: true, attributes: true })`. ## Delivery is asynchronous Records are queued and handed to your callback later as an array, never synchronously during the DOM write. Code that mutates and then immediately inspects a counter the callback increments will see the old value. Reach for `takeRecords()` when you need whatever is queued right now. ## Practical shape Pick the narrowest options that answer your question. `{ childList: true }` on a specific list container is cheap and precise; `{ childList: true, subtree: true, attributes: true }` on `document.body` sees every change in the application and pays for all of them. When you only care about one attribute, add `attributeFilter: ['data-state']` so unrelated attribute writes never allocate a record at all.