useMutationObserver

Reactive wrapper around the MutationObserver API. Observes one or more DOM nodes for mutations — attribute changes, child additions/removals, and text content changes. Targets can be Ref$, MaybeElement, or a plain Element.

Demo

status: observingdata-active: —children: 0
DOM
Observer
— no mutations recorded yet

Usage

import { 
function useRef$<T extends Element = Element>(externalRef?: React.Ref<T> | null): Ref$<T>
Creates an observable element ref. Can be used as a drop-in replacement for
useRef, composed with callback refs, or used with forwardRef.
The element is wrapped with opaqueObject to prevent legendapp/state
from making DOM properties reactive (deep observation).
@param ― externalRef - Optional. Accepts callback ref, RefObject, or null (forwardRef compatible).
@returns ― A callable ref that is also observable via get/peek
@example 
// standalone — useRef replacement
const el$ = useRef$<HTMLDivElement>();
return <div ref={el$} />;

// forwardRef compatible
const Component = forwardRef<HTMLDivElement>((props, ref) => {
  const el$ = useRef$(ref);
  return <div ref={el$} />;
});

// callback ref composition
const myRef = useCallback((node: HTMLDivElement | null) => {
  node?.focus();
}, []);
const el$ = useRef$(myRef);
return <div ref={el$} />;
useRef$, 
import useMutationObserver
useMutationObserver } from "@usels/core";
function 
function Component(): React.JSX.Element
Component() {
  const 
const el$: Ref$<HTMLDivElement>
el$ = 
useRef$<HTMLDivElement>(externalRef?: React.Ref<HTMLDivElement> | undefined): Ref$<HTMLDivElement>
Creates an observable element ref. Can be used as a drop-in replacement for
useRef, composed with callback refs, or used with forwardRef.
The element is wrapped with opaqueObject to prevent legendapp/state
from making DOM properties reactive (deep observation).
@param ― externalRef - Optional. Accepts callback ref, RefObject, or null (forwardRef compatible).
@returns ― A callable ref that is also observable via get/peek
@example 
// standalone — useRef replacement
const el$ = useRef$<HTMLDivElement>();
return <div ref={el$} />;

// forwardRef compatible
const Component = forwardRef<HTMLDivElement>((props, ref) => {
  const el$ = useRef$(ref);
  return <div ref={el$} />;
});

// callback ref composition
const myRef = useCallback((node: HTMLDivElement | null) => {
  node?.focus();
}, []);
const el$ = useRef$(myRef);
return <div ref={el$} />;
useRef$<
interface HTMLDivElement
HTMLDivElement>();

  
import useMutationObserver
useMutationObserver(
    
const el$: Ref$<HTMLDivElement>
el$,
    (
records: any
records) => {
      
records: any
records.
any
forEach((
r: any
r) => {
        /* handle r.type, r.target */
      });
    },
    { 
attributes: boolean
attributes: true, 
childList: boolean
childList: true }
  );

  return <
React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>
div 
React.RefAttributes<HTMLDivElement>.ref?: React.Ref<HTMLDivElement> | undefined
Allows getting a ref to the component instance.
Once the component unmounts, React will set ref.current to null
(or call the ref with null if you passed a callback ref).
@see ― https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs
ref={
const el$: Ref$<HTMLDivElement>
el$} />;
}

Watching attributes only

useMutationObserver(el$, callback, { attributes: true });

Filtering specific attributes

Only fire when aria-expanded or data-active change:

useMutationObserver(el$, callback, {
  attributes: true,
  attributeFilter: ["aria-expanded", "data-active"],
});

Recording the previous attribute value

useMutationObserver(
  el$,
  (records) => {
    records.forEach((r) => {
      const next = (r.target as Element).getAttribute(r.attributeName!);
      console.log("old:", r.oldValue, "→ new:", next);
    });
  },
  { attributes: true, attributeOldValue: true }
);

Watching descendant nodes with `subtree`

useMutationObserver(el$, callback, { childList: true, subtree: true });

Multiple targets

useMutationObserver([el$, anotherEl], callback, { attributes: true });

Stop and resume

const { stop, resume } = useMutationObserver(el$, callback, { childList: true });

stop(); // disconnects the observer
resume(); // reconnects with the same target and options

Flushing pending records

const { takeRecords } = useMutationObserver(el$, callback, { attributes: true });

const pending = takeRecords();

Checking browser support

const { isSupported$ } = useMutationObserver(el$, callback, { attributes: true });

console.log(isSupported$.get()); // Observable<boolean>

Type Declarations

export interface UseMutationObserverOptions extends MutationObserverInit {
}
export interface UseMutationObserverReturn {
    isSupported$: Observable<boolean>;
    stop: () => void;
    resume: () => void;
    takeRecords: () => MutationRecord[];
}
export declare function useMutationObserver(target: MaybeElement | MaybeElement[], callback: MutationCallback, options?: UseMutationObserverOptions): UseMutationObserverReturn;

Source

View on GitHub

Contributors

tigerwest

Changelog

a7392ab 2026-03-06 - feat(core,browser): add sync strategy hooks (tigerwest)