useMutationObserver
A composable for detecting DOM changes using the Mutation Observer API with automatic cleanup.
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.
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.
<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
Add and remove child elements, toggle attributes, and observe the mutation log in real time, with pause/resume and clear controls.
Functions
useMutationObserver
(target: MaybeElementRef, callback: (entries: MutationObserverRecord[]) => void, options?: UseMutationObserverOptions) => UseMutationObserverReturnA composable that uses the Mutation Observer API to detect changes in the DOM.
Options
immediate
boolean | undefinedonce
boolean | undefinedchildList
boolean | undefinedattributes
boolean | undefinedcharacterData
boolean | undefinedsubtree
boolean | undefinedattributeOldValue
boolean | undefinedcharacterDataOldValue
boolean | undefinedattributeFilter
string[] | undefinedProperties
isActive
Readonly<Ref<boolean, boolean>>Whether the observer is currently active (created and observing)