Mutation Observer

Primitive providing the ability to watch for changes made to the DOM tree.

Stage	Category	Version	Last Updated	Demo
3	Browser APIs	3.0.0-next.2 (next)	Aug 13, 2026	Demo →

npm i @solid-primitives/mutation-observer@next

Primitive providing the ability to watch for changes made to the DOM tree. A wrapper for Browser's MutationObserver API.

How to use it

createMutationObserver

import { createMutationObserver } from "@solid-primitives/mutation-observer";

// Use the returned `add` as a ref — options are set at creation time:
const [add] = createMutationObserver([], { childList: true }, records => console.log(records));
<div ref={add} />

// Observe multiple elements:
const [add, { start, stop }] = createMutationObserver(
  () => [el1, el2, el3],
  { attributes: true, subtree: true },
  records => console.log(records)
);

// Per-element options:
createMutationObserver(
  [[el, { attributes: true }], [el1, { childList: true }]],
  records => console.log(records)
);

Automatically starts observing after the component settles (via onSettled) and disconnects on cleanup. You can also control observation manually with start() and stop().

Standalone Ref

mutationObserver is a convenience for observing a single element without calling createMutationObserver separately:

import { mutationObserver } from "@solid-primitives/mutation-observer";

<div ref={mutationObserver({ childList: true }, records => console.log(records))} />;

Types

function createMutationObserver(
  initial: MaybeAccessor<Node | Node[]>,
  options: MutationObserverInit,
  callback: MutationCallback,
): MutationObserverReturn;
function createMutationObserver(
  initial: MaybeAccessor<[Node, MutationObserverInit][]>,
  callback: MutationCallback,
): MutationObserverReturn;

type MutationObserverReturn = [
  add: MutationObserverAdd,
  rest: {
    start: Fn;
    stop: Fn;
    instance: MutationObserver;
    isSupported: boolean;
  },
];

type MutationObserverAdd = (target: Node, options?: MaybeAccessor<MutationObserverInit>) => void;

const mutationObserver: (
  options: MutationObserverInit,
  callback: MutationCallback,
) => (target: Element) => void;

Changelog

See CHANGELOG.md