useMutationObserver

A composable for detecting DOM changes using the Mutation Observer API with automatic cleanup.

Copy Markdown

StableAdvancedJun 29, 2026

Usage

The useMutationObserver composable wraps the Mutation Observer API to detect changes to the DOM tree. It’s useful for monitoring attribute changes, child element modifications, and character data updates.

Tip

Why wrap MutationObserver? The native MutationObserver has no awareness of Vue’s effectScope lifecycle. If you create one inside a composable, it won’t automatically disconnect when the scope is disposed. useMutationObserver integrates onScopeDispose for automatic cleanup, defers creation until after hydration for SSR safety, and adds reactive target tracking — things the native API can’t do on its own.

vue

<script setup lang="ts">
  import { useMutationObserver } from '@vuetify/v0'
  import { ref, useTemplateRef } from 'vue'

  const target = useTemplateRef('target')
  const mutationCount = ref(0)

  useMutationObserver(target, (mutations) => {
    mutationCount.value += mutations.length
    mutations.forEach(mutation => {
      console.log('Type:', mutation.type)
      console.log('Added nodes:', mutation.addedNodes)
      console.log('Removed nodes:', mutation.removedNodes)
    })
  }, {
    childList: true,
    attributes: true,
    attributeOldValue: true
  })
</script>

<template>
  <div>
    <div ref="target">
      <p>Mutations detected: {{ mutationCount }}</p>
    </div>
  </div>
</template>

Architecture

useMutationObserver wraps the native MutationObserver API with Vue reactivity:

Options

Option	Type	Default	Notes
`immediate`	`boolean`	`false`	Fire the callback immediately on mount before any mutation
`once`	`boolean`	`false`	Stop observing after the first callback fires
`childList`	`boolean`	`true`	Observe child node additions and removals
`attributes`	`boolean`	`false`	Observe attribute changes
`characterData`	`boolean`	`false`	Observe text content changes
`subtree`	`boolean`	`false`	Extend observation to all descendant nodes
`attributeFilter`	`string[]`	—	Limit attribute observation to specific attribute names
`characterDataOldValue`	`boolean`	`false`	Record previous text value in mutation records

Reactivity

Property/Method	Reactive	Notes
`isActive`		Computed from observer ref
`isPaused`		ShallowRef, readonly
`target`		Accepts MaybeRef, watched for changes
`pause()`	—	Temporarily stop observing without disconnecting
`resume()`	—	Resume after `pause()`
`stop()`	—	Disconnect the observer permanently

Examples

DOM Mutation Logger

An interactive sandbox that fires three distinct mutation types at the Mutation Observer: childList changes when children are added or removed via the Add/Remove buttons; attributes changes when the Toggle Attribute button flips data-highlighted on the root; and characterData changes propagate up from any descendant text node thanks to subtree: true. Every batch of MutationRecord objects that the callback receives is appended to a color-coded log entry below the target, labeled by type and detail.

The example exercises pause() and resume() so you can see that mutations fired while the observer is paused are silently dropped — the log does not catch up when observing resumes. The isPaused ref drives the button label reactively without any extra watcher. Use this pattern in performance-sensitive trees where you need to defer observation during bulk DOM writes, then resume once the work is complete. For size-change tracking, prefer useResizeObserver; for DOM-presence detection, prefer useIntersectionObserver.

Add children to observe mutations

Mutation Log (0)

No mutations recorded yet

FAQ

Discord

Need help? Join our community for support and discussions ↗

API Reference

The following API details are for the useMutationObserver composable.

useMutationObserver

1 function, 9 options, 2 properties, 3 methods