mutation-observer

Observe DOM mutations of reactive elements.


Package	`@vizejs/composable/mutation-observer`
Own the source	`vize lib pull composable:mutation-observer`
Runtime exports	`useMutationObserver`
Gzip budget	2304 B

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/composable

Import the entry directly. Call lifecycle-bound utilities inside <script setup> so cleanup follows the component scope; consult the runtime contract for this entry's SSR and hydration behavior.

import { useMutationObserver } from "@vizejs/composable/mutation-observer";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useMutationObserver`	dom	experimental	deterministic-fallback	stable	caller, reactive-scope	web, desktop	`globalThis`, `MutationObserver`	`resolveElements`, `tryOnScopeDispose`

API

`useMutationObserver`

Observe DOM mutations of reactive elements. The observer is recreated when the resolved targets or host change and is disconnected when the owning reactive scope stops. At least one of attributes, childList, or characterData must be enabled (directly or implicitly), mirroring the platform contract. No work happens during server rendering.

function useMutationObserver( targets: MaybeElementTargets, callback: MutationCallback, options: UseMutationObserverOptions = {}, ): MutationObserverControls

Types

`MutationObserverHost`

Runtime capability that supplies the MutationObserver constructor.

Member	Type	Description
`MutationObserver`?	`new (callback: MutationCallback) => MutationObserver`	`MutationObserver` constructor, absent in unsupported runtimes.

`UseMutationObserverOptions`

Options for useMutationObserver.

Member	Type	Description
`attributes`?	`boolean`	Observe attribute changes.
`childList`?	`boolean`	Observe child-list changes.
`subtree`?	`boolean`	Extend observation to the whole subtree.
`characterData`?	`boolean`	Observe text-content changes.
`attributeOldValue`?	`boolean`	Record the previous attribute value.
`characterDataOldValue`?	`boolean`	Record the previous text value.
`attributeFilter`?	`readonly string[]`	Restrict attribute observation to these local names.
`host`?	`MaybeRefOrGetter<MutationObserverHost \| null \| undefined>`	Reactive constructor capability for alternate runtimes and tests.
`flush`?	`"pre" \| "post" \| "sync"`	Target resolution timing. `"post"` observes template refs after mount.

`MutationObserverControls`

Controls returned by useMutationObserver.

Member	Type	Description
`isSupported`	`Readonly<Ref<boolean>>`	Whether the host provides `MutationObserver`. `false` during server rendering.
`takeRecords`	`() => MutationRecord[]`	Drain the records queued by the active observer without invoking the callback.
`stop`	`() => void`	Disconnect permanently. Idempotent.