MutationObserver in JavaScript

// Watch for any changes to a DOM element
const observer = new MutationObserver((mutations) => {
  for (const mutation of mutations) {
    console.log('Something changed!', mutation.type)
  }
})

observer.observe(document.body, {
  childList: true,   // Watch for added/removed children
  subtree: true      // Watch all descendants too
})

// These changes happen silently - no events fired!
element.setAttribute('data-active', 'true')
element.textContent = 'New text'
element.appendChild(newChild)

// There's no "attributechange" or "childadded" event to listen for
element.addEventListener('attributechange', handler)  // This doesn't exist!

┌─────────────────────────────────────────────────────────────────────────┐
│                    THE SECURITY CAMERA ANALOGY                           │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│   YOUR DOM                                MUTATIONOBSERVER               │
│   ┌──────────────────────┐               ┌──────────────────┐           │
│   │                      │               │                  │           │
│   │  ┌────────────────┐  │    watches    │   📹 Camera      │           │
│   │  │  <div>         │◄─┼───────────────┤                  │           │
│   │  │    <p>Hi</p>   │  │               │   Config:        │           │
│   │  │    <span/>     │  │               │   - children ✓   │           │
│   │  │  </div>        │  │               │   - attributes ✓ │           │
│   │  └────────────────┘  │               │   - text ✓       │           │
│   │                      │               │                  │           │
│   └──────────────────────┘               └────────┬─────────┘           │
│                                                   │                      │
│                                                   │ detects changes      │
│                                                   ▼                      │
│                                          ┌──────────────────┐           │
│                                          │  YOUR CALLBACK   │           │
│                                          │                  │           │
│                                          │  "A child was    │           │
│                                          │   added!"        │           │
│                                          │  "Attribute      │           │
│                                          │   changed!"      │           │
│                                          └──────────────────┘           │
│                                                                          │
│   Just like a security camera:                                           │
│   • You choose WHAT to watch (which element)                             │
│   • You choose WHAT to detect (motion, faces, etc. = children, attrs)    │
│   • You get NOTIFIED when something happens (callback with details)      │
│   • You can STOP watching anytime (disconnect)                           │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

```javascript
const observer = new MutationObserver((mutations, obs) => {
  // mutations = array of MutationRecord objects
  // obs = the observer itself (useful for disconnecting)
  console.log(`${mutations.length} changes detected`)
})
```

```javascript
const targetElement = document.getElementById('app')

observer.observe(targetElement, {
  childList: true,    // Watch for added/removed children
  attributes: true,   // Watch for attribute changes
  characterData: true // Watch for text content changes
})
```

```javascript
const observer = new MutationObserver((mutations) => {
  for (const mutation of mutations) {
    if (mutation.type === 'childList') {
      console.log('Children changed!')
      console.log('Added:', mutation.addedNodes)
      console.log('Removed:', mutation.removedNodes)
    }
    if (mutation.type === 'attributes') {
      console.log(`Attribute "${mutation.attributeName}" changed`)
    }
  }
})
```

// Triggers when:
container.appendChild(newElement)     // ✓
container.removeChild(existingChild)  // ✓
container.innerHTML = '<p>New</p>'    // ✓
container.setAttribute('class', 'x')  // ✗ (not watching attributes)
```

// Triggers when:
element.setAttribute('data-active', 'true')  // ✓
element.classList.add('highlight')           // ✓
element.id = 'new-id'                        // ✓
element.textContent = 'New text'             // ✗ (not watching characterData)
```

// Triggers when:
element.classList.toggle('active')        // ✓ (class is in filter)
element.dataset.state = 'loading'         // ✓ (data-state is in filter)
element.setAttribute('title', 'Hello')    // ✗ (title not in filter)
```

// Triggers for ANY change anywhere in the body!
// Use with caution - can be expensive
```

const observer = new MutationObserver((mutations) => {
  for (const mutation of mutations) {
    switch (mutation.type) {
      case 'childList':
        // Nodes were added or removed
        mutation.addedNodes.forEach(node => {
          if (node.nodeType === Node.ELEMENT_NODE) {
            console.log('Element added:', node.tagName)
          }
        })
        mutation.removedNodes.forEach(node => {
          if (node.nodeType === Node.ELEMENT_NODE) {
            console.log('Element removed:', node.tagName)
          }
        })
        break
        
      case 'attributes':
        // An attribute changed
        console.log(
          `Attribute "${mutation.attributeName}" changed on`,
          mutation.target,
          `from "${mutation.oldValue}" to "${mutation.target.getAttribute(mutation.attributeName)}"`
        )
        break
        
      case 'characterData':
        // Text content changed
        console.log(
          'Text changed from',
          `"${mutation.oldValue}" to "${mutation.target.textContent}"`
        )
        break
    }
  }
})

observer.observe(element, {
  childList: true,
  attributes: true,
  characterData: true,
  subtree: true,
  attributeOldValue: true,
  characterDataOldValue: true
})

// Without subtree - only watches direct children
observer.observe(parent, { childList: true })

// parent
// ├── child1     ← Watched
// │   └── grandchild1  ← NOT watched
// └── child2     ← Watched
//     └── grandchild2  ← NOT watched


// With subtree - watches entire tree
observer.observe(parent, { childList: true, subtree: true })

// parent
// ├── child1     ← Watched
// │   └── grandchild1  ← Watched
// └── child2     ← Watched
//     └── grandchild2  ← Watched

const observer = new MutationObserver(callback)
observer.observe(element, { childList: true })

// Later, when you're done watching
observer.disconnect()

// The callback will no longer fire for any changes

// Get any mutations that haven't been delivered to the callback yet
const pendingMutations = observer.takeRecords()

// Process them manually
for (const mutation of pendingMutations) {
  console.log('Pending mutation:', mutation.type)
}

// Now disconnect
observer.disconnect()

class MyComponent {
  constructor(element) {
    this.element = element
    this.observer = new MutationObserver(this.handleMutations.bind(this))
    this.observer.observe(element, { childList: true, subtree: true })
  }
  
  handleMutations(mutations) {
    // Process mutations
  }
  
  destroy() {
    // Always clean up!
    this.observer.disconnect()
    this.observer = null
  }
}

console.log('1. Script start')

const observer = new MutationObserver(() => {
  console.log('3. MutationObserver callback')
})
observer.observe(document.body, { childList: true })

document.body.appendChild(document.createElement('div'))

Promise.resolve().then(() => {
  console.log('2. Promise callback')
})

console.log('4. Script end')

// Output:
// 1. Script start
// 4. Script end
// 2. Promise callback
// 3. MutationObserver callback

const imageObserver = new MutationObserver((mutations) => {
  for (const mutation of mutations) {
    for (const node of mutation.addedNodes) {
      if (node.nodeType !== Node.ELEMENT_NODE) continue
      
      // Check if the added node is an image with data-src
      if (node.matches('img[data-src]')) {
        loadImage(node)
      }
      
      // Also check children of the added node
      node.querySelectorAll('img[data-src]').forEach(loadImage)
    }
  }
})

function loadImage(img) {
  img.src = img.dataset.src
  img.removeAttribute('data-src')
}

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

const codeObserver = new MutationObserver((mutations) => {
  for (const mutation of mutations) {
    for (const node of mutation.addedNodes) {
      if (node.nodeType !== Node.ELEMENT_NODE) continue
      
      // Find code blocks in the added content
      const codeBlocks = node.matches('pre code') 
        ? [node] 
        : node.querySelectorAll('pre code')
      
      codeBlocks.forEach(block => {
        if (!block.dataset.highlighted) {
          Prism.highlightElement(block)
          block.dataset.highlighted = 'true'
        }
      })
    }
  }
})

codeObserver.observe(document.getElementById('content'), {
  childList: true,
  subtree: true
})

const adBlocker = new MutationObserver((mutations) => {
  for (const mutation of mutations) {
    for (const node of mutation.addedNodes) {
      if (node.nodeType !== Node.ELEMENT_NODE) continue
      
      if (node.matches('.ad-banner, [data-ad], .sponsored')) {
        node.remove()
        console.log('Blocked unwanted element')
      }
    }
  }
})

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

const form = document.getElementById('editor-form')
let saveTimeout

const formObserver = new MutationObserver(() => {
  // Debounce the save
  clearTimeout(saveTimeout)
  saveTimeout = setTimeout(() => {
    saveFormData(form)
  }, 1000)
})

formObserver.observe(form, {
  childList: true,
  subtree: true,
  attributes: true,
  characterData: true
})

function saveFormData(form) {
  const data = new FormData(form)
  console.log('Auto-saving...', Object.fromEntries(data))
  // Send to server
}

const element = document.getElementById('panel')

const classObserver = new MutationObserver((mutations) => {
  for (const mutation of mutations) {
    if (mutation.attributeName === 'class') {
      const currentClasses = mutation.target.classList
      
      if (currentClasses.contains('expanded')) {
        console.log('Panel expanded!')
        loadPanelContent()
      } else {
        console.log('Panel collapsed!')
      }
    }
  }
})

classObserver.observe(element, {
  attributes: true,
  attributeFilter: ['class']
})

// ❌ WRONG - processes text nodes and comments too
const observer = new MutationObserver((mutations) => {
  for (const mutation of mutations) {
    for (const node of mutation.addedNodes) {
      console.log('Added:', node.tagName)  // undefined for text nodes!
    }
  }
})

// ✓ CORRECT - filter for elements only
const observer = new MutationObserver((mutations) => {
  for (const mutation of mutations) {
    for (const node of mutation.addedNodes) {
      if (node.nodeType === Node.ELEMENT_NODE) {
        console.log('Added element:', node.tagName)
      }
    }
  }
})

// ❌ WRONG - modifying the DOM inside the callback that watches for modifications
const observer = new MutationObserver((mutations) => {
  for (const mutation of mutations) {
    // This causes another mutation, which fires the callback again!
    mutation.target.setAttribute('data-processed', 'true')
  }
})

observer.observe(element, { attributes: true })

// ✓ CORRECT - guard against reprocessing
const observer = new MutationObserver((mutations) => {
  for (const mutation of mutations) {
    if (mutation.target.dataset.processed) continue  // Skip already processed
    mutation.target.dataset.processed = 'true'
  }
})

// Or better - exclude the attribute you're setting
observer.observe(element, {
  attributes: true,
  attributeFilter: ['class', 'data-state']  // Don't include 'data-processed'
})

// ❌ WRONG - observer keeps running after element is removed
function setupWidget(container) {
  const observer = new MutationObserver(handleChanges)
  observer.observe(container, { childList: true })
  
  // Container gets removed later, but observer is never disconnected
  // Memory leak!
}

// ✓ CORRECT - clean up when done
function setupWidget(container) {
  const observer = new MutationObserver(handleChanges)
  observer.observe(container, { childList: true })
  
  // Return cleanup function
  return () => observer.disconnect()
}

const cleanup = setupWidget(myContainer)
// Later when removing the widget:
cleanup()

// ❌ WRONG - watching everything everywhere
observer.observe(document.body, {
  childList: true,
  attributes: true,
  characterData: true,
  subtree: true,
  attributeOldValue: true,
  characterDataOldValue: true
})

// ✓ CORRECT - be specific about what you need
observer.observe(specificContainer, {
  childList: true,
  subtree: true
  // Only watch what you actually need
})

1. **childList** — Child nodes being added or removed
2. **attributes** — Attribute values changing
3. **characterData** — Text content changing in text nodes

Each mutation type corresponds to a `type` property value in the MutationRecord.

Without `subtree`, only immediate children of the observed element trigger mutations. With `subtree`, changes anywhere in the element's entire tree trigger mutations.

```javascript
// Only direct children
observer.observe(parent, { childList: true })

// All descendants
observer.observe(parent, { childList: true, subtree: true })
```

1. After the current synchronous script finishes
2. After all pending microtasks (like Promise callbacks)
3. Before the browser renders/paints

Multiple DOM changes are batched and delivered in a single callback invocation.

```javascript
const observer = new MutationObserver(callback)
observer.observe(element, { childList: true })

// Stop watching
observer.disconnect()
```

If you need to process pending mutations before disconnecting, call `takeRecords()` first.

- Text nodes (nodeType 3)
- Comment nodes (nodeType 8)
- Element nodes (nodeType 1)

If you only care about elements, filter by `node.nodeType === Node.ELEMENT_NODE`:

```javascript
for (const node of mutation.addedNodes) {
  if (node.nodeType === Node.ELEMENT_NODE) {
    // This is an actual element
  }
}
```

```javascript
// Infinite loop - setting an attribute inside a callback 
// that watches attributes!
const observer = new MutationObserver((mutations) => {
  element.setAttribute('data-count', count++)  // Triggers another mutation!
})
observer.observe(element, { attributes: true })
```

**Solutions:**
- Use `attributeFilter` to exclude the attribute you're modifying
- Add a guard condition to skip already-processed elements
- Set a flag before modifying and check it in the callback