useMutationObserver

A React hook for observing changes to the DOM using the Mutation Observer API

Mutation Observer Demo

Watch how the hook detects DOM changes in real-time

Target Element

Mutation Count: 0

Installation

Props

Prop	Type	Default	Description
`target`	`React.RefObject<T \| null>`	-	The DOM element to observe
`options`	`MutationObserverInit`	See below	Configuration for the mutation observer
`callback`	`MutationCallback`	-	Function called when mutations are observed

Options

Prop	Type	Default	Description
`attributes`	`boolean`	`true`	Whether to observe attribute changes
`childList`	`boolean`	`true`	Whether to observe child node changes
`subtree`	`boolean`	`true`	Whether to observe changes in the entire subtree of the target element

Data

The hook returns an object with the following properties:

Property	Type	Description
`disconnect`	`() => void`	Function to disconnect the mutation observer

Key Features & Details

Browser Support

The Mutation Observer API is well-supported across modern browsers:

Chrome: Full support
Firefox: Full support
Safari: Full support
Edge: Full support
Opera: Full support

Cross-Browser Compatibility

The hook handles browser-specific implementations and edge cases
Provides consistent behavior across different browsers
Gracefully handles cases where the API might not be fully supported

Performance Considerations

The hook automatically disconnects observers when components unmount
Provides a disconnect function for manual cleanup
Supports configurable observation options to optimize performance
Handles edge cases where the target element might be null

Best Practices & Caveats

Always provide a target element
Use the disconnect function when you no longer need to observe changes
Be mindful of performance when observing large subtrees
Consider using specific options to limit the types of mutations you observe
Clean up observers when components unmount
Use appropriate options based on your use case
Handle edge cases where the target element might be null
Consider debouncing or throttling the callback for performance

Examples

Basic Usage

const [mutations, setMutations] = useState<MutationRecord[]>([]);
const targetRef = useRef<HTMLDivElement | null>(null);
 
useMutationObserver<HTMLDivElement>({
  target: targetRef,
  callback: (mutationsList) => {
    setMutations((prev) => [...prev, ...mutationsList]);
  },
});
 
return <div ref={targetRef}>Target Element</div>;

With Custom Options

useMutationObserver<HTMLDivElement>({
  target: targetRef,
  callback: (mutationsList) => {
    // Handle mutations
  },
  options: {
    attributes: true,
    childList: false,
    subtree: false,
  },
});

With Disconnect

const { disconnect } = useMutationObserver<HTMLDivElement>({
  target: targetRef,
  callback: (mutationsList) => {
    // Handle mutations
  },
});
 
// Later, when you want to stop observing
disconnect();

Usage

import { useMutationObserver } from '@/hooks/use-mutation-observer';
 
function MyComponent() {
  const targetRef = useRef<HTMLDivElement | null>(null);
  const [mutations, setMutations] = useState<MutationRecord[]>([]);
 
  useMutationObserver<HTMLDivElement>({
    target: targetRef,
    callback: (mutationsList) => {
      setMutations((prev) => [...prev, ...mutationsList]);
    },
  });
 
  return <div ref={targetRef}>Target Element</div>;
}

Common Use Cases

Dynamic Content Loading: Observe when new content is added to a container
Form Validation: Watch for attribute changes on form elements
UI State Management: Track changes to UI elements for state synchronization
Third-party Integration: Monitor changes made by third-party scripts
Accessibility: Track changes that might affect accessibility