DEV Community: reactuse.com

Animating React Without Fighting the Render Loop: useRafFn, useRafState, useFps, useDevicePixelRatio, useUpdate

reactuse.com — Wed, 27 May 2026 08:02:10 +0000

Animating React Without Fighting the Render Loop: useRafFn, useRafState, useFps, useDevicePixelRatio, useUpdate

React owns one clock and the browser owns another. React's reconciler decides when components re-render based on state updates, effects, and the scheduler's idea of "soon". The browser's compositor paints the screen at whatever rate the display can sustain — sixty frames a second on most monitors, a hundred and twenty on a few. The two clocks are not synced. State updates can land between paints and get coalesced; long render trees can miss a paint entirely; a setInterval(handler, 16) will drift by hundreds of milliseconds over a minute because setInterval does not care what the GPU is doing.

The standard fix is requestAnimationFrame. It hands you a callback that fires just before the next paint, with a high-resolution timestamp, throttled automatically when the tab is hidden. It is the right primitive for everything that has to look smooth. It is also tedious to wire up correctly in React: you need a ref to hold the frame ID, an effect to start the loop, a cleanup to cancel it on unmount, a useLatest so the callback sees fresh props, and another ref if you want pause/resume. Every animated component reinvents this scaffolding, and most of them get one of the cleanups wrong the first time around.

ReactUse bundles the scaffolding into five hooks that share the same underlying loop. This post walks each one — useRafFn for the loop itself, useRafState for state that updates with the loop, useFps for measuring the loop, useDevicePixelRatio for drawing into the loop at the right resolution, and useUpdate for the cases where you need to nudge React but do not have state to change. Together they cover almost everything you would build outside of a dedicated animation library.

The Bug, in One Component

A draggable card that follows the mouse:

function FloatingCard() {
  const [pos, setPos] = useState({ x: 0, y: 0 });

  useEffect(() => {
    const move = (e: MouseEvent) => setPos({ x: e.clientX, y: e.clientY });
    window.addEventListener('mousemove', move);
    return () => window.removeEventListener('mousemove', move);
  }, []);

  return (
    <div
      style={{
        position: 'fixed',
        left: pos.x,
        top: pos.y,
        transform: 'translate(-50%, -50%)',
      }}
    >
      card
    </div>
  );
}

Looks fine. Now open the devtools profiler and wave the mouse across the screen. On a fast laptop mousemove fires somewhere between 120 and 500 times a second, depending on the input device and the OS. Every one of those events calls setPos, which schedules a re-render, which React batches into the next microtask. You are doing two to eight times more reconciliation work than the screen can possibly show, and the extra renders are pure overhead — the only one that mattered was the last one before the next paint.

useRafState collapses that into one update per frame, no matter how fast the events come in. Drop-in replacement, same [state, setState] API, three fewer reconciliations per mouse twitch. The rest of the hooks in this post follow the same pattern: keep the React-shaped API, hide the requestAnimationFrame plumbing.

1. useRafFn — The Loop, With Pause and Resume

useRafFn is the primitive everything else builds on. It takes a callback and runs it on every requestAnimationFrame tick, passing the high-resolution timestamp. It returns [stop, start, isActive] so you can pause the loop on tab blur, user interaction, or any other signal:

import { useRef } from 'react';
import { useRafFn } from '@reactuses/core';

function StarField({ count = 200 }: { count?: number }) {
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const starsRef = useRef(
    Array.from({ length: count }, () => ({
      x: Math.random(),
      y: Math.random(),
      z: Math.random() * 0.5 + 0.5,
    })),
  );

  const [stop, start, isActive] = useRafFn((time) => {
    const canvas = canvasRef.current;
    if (!canvas) return;
    const ctx = canvas.getContext('2d')!;
    const { width, height } = canvas;

    ctx.fillStyle = '#000';
    ctx.fillRect(0, 0, width, height);

    const t = time / 1000;
    for (const star of starsRef.current) {
      const x = ((star.x + t * 0.02 * star.z) % 1) * width;
      const y = star.y * height;
      ctx.fillStyle = `rgba(255, 255, 255, ${star.z})`;
      ctx.fillRect(x, y, 2, 2);
    }
  });

  return (
    <>
      <canvas ref={canvasRef} width={600} height={400} />
      <button onClick={() => (isActive() ? stop() : start())}>
        {isActive() ? 'Pause' : 'Resume'}
      </button>
    </>
  );
}

Four design choices in that hook worth understanding. The callback runs just before paint — requestAnimationFrame semantics — so any DOM read inside it sees the same layout the paint will use, with no extra forced reflow. The callback identity is wrapped in useLatest, so you can close over fresh props (count, anything in scope) without restarting the loop. The loop auto-starts on mount; pass false as the second argument if you want manual control from the first frame. And the cleanup is registered with the effect, so unmounting cancels the pending frame — no rogue callbacks running on a dead component.

The isActive return is a function, not a boolean. Reading it inside an event handler always gives the current value; reading it in render only sees the value at render time. That asymmetry catches people. If you want the active flag in the JSX for a disabled={} prop, pair useRafFn with useUpdate and call update() inside stop/start callers — the demo above gets away without it because the button label is regenerated on the next click anyway.

A real-world use beyond canvas is anything tracking time between events. A physics simulation that needs to integrate velocity by delta time. A scrub bar that tracks media element currentTime without the chunky timeupdate event (which fires at the codec's leisure, not yours). A custom cursor that lags behind the real one with a spring — useRafFn reads the latest target position, applies the spring step, writes the result to a CSS variable. All of those replace setInterval patterns that drift and burn battery in the background tab.

2. useRafState — useState That Coalesces Per Frame

useRafState is the version of the floating-card example you actually ship:

import { useRafState } from '@reactuses/core';
import { useEventListener } from '@reactuses/core';

function FloatingCard() {
  const [pos, setPos] = useRafState({ x: 0, y: 0 });

  useEventListener('mousemove', (e) => {
    setPos({ x: e.clientX, y: e.clientY });
  });

  return (
    <div
      style={{
        position: 'fixed',
        left: pos.x,
        top: pos.y,
        transform: 'translate(-50%, -50%)',
        transition: 'transform 0.1s',
      }}
    >
      card
    </div>
  );
}

The API is exactly useState — same setter signature, same updater-function support — but writes are queued through requestAnimationFrame. Five setPos calls in the same frame collapse into one React update; the React update flushes at most once per paint; the DOM gets updated at the same rate the screen is refreshing. The mousemove listener still fires at 500Hz, which costs about as much as an empty function call. The reconciliation cost drops to 60Hz, which is what the screen can show anyway.

A few things to know. The hook keys updates by a single pending requestAnimationFrame ID per state slot, so consecutive setters within a frame replace rather than queue — the last value wins. That is almost always what you want for visual state: you do not care about the intermediate mouse positions, only where the cursor is at paint time. If you do care — if you are sampling sensor data and need every value — use plain useState and accept the re-render cost, or buffer into a ref and flush on a useRafFn tick.

The cleanup detail is the same as useRafFn: a pending frame is cancelled on unmount, so a fast click-drag-unmount sequence does not produce a setState on unmounted component warning. Internally it is useState + useRef for the frame ID + useUnmount cleanup, about twenty lines total. You could write it yourself; the hook saves you from having to.

There is one gotcha. Because the state lags one frame behind the event, code reading the state immediately after calling the setter will still see the old value:

setPos({ x: 100, y: 100 });
console.log(pos); // still { x: 0, y: 0 } — update hasn't run yet

With plain useState this is also true within the same render cycle, but the lag of one whole frame can surprise you when wiring imperative code together. If you need the value back, store it in a ref alongside.

3. useFps — Measuring What You Built

useRafFn and useRafState both improve smoothness, but smoothness is a measured quantity, not a feeling. useFps returns the current frame rate as a number, computed by counting how often the underlying requestAnimationFrame callback fires:

import { useFps } from '@reactuses/core';

function FpsOverlay() {
  const fps = useFps();
  const color = fps >= 55 ? 'green' : fps >= 30 ? 'orange' : 'red';

  return (
    <div
      style={{
        position: 'fixed',
        top: 8,
        right: 8,
        padding: '4px 8px',
        background: 'rgba(0,0,0,0.7)',
        color,
        fontFamily: 'monospace',
      }}
    >
      {fps} fps
    </div>
  );
}

Drop that into a dev build and you have the FPS counter you would normally reach for Chrome's rendering panel to get. The hook accepts an every option (default 10) that controls how many frames it averages over; smaller numbers respond faster to a hitch but jitter more, larger numbers smooth out the readout but lag behind a sudden drop. Ten is a fine default for a corner overlay; one or two is what you want if you are debugging a specific janky transition.

The more interesting use is adaptive rendering. Read the FPS, and when it drops below a threshold, reduce the work you are doing:

function ParticleSystem({ baseCount = 1000 }: { baseCount?: number }) {
  const fps = useFps({ every: 30 });
  const count =
    fps >= 55 ? baseCount : fps >= 40 ? baseCount / 2 : baseCount / 4;

  return <Particles count={count} />;
}

That is the same trick AAA game engines pull when the frame budget tightens — drop particle counts, reduce shadow resolution, switch a fluid simulation to a lower grid. For a React app it is usually enough to halve the count of an animated background, or stop running a non-essential useRafFn loop entirely. The threshold values are taste; 55 is a reasonable "we are basically fine" line on a 60Hz display, since the average can dip into the high fifties just from GC pauses without anyone noticing.

A note on SSR: the hook returns 0 on the server, so do not gate critical UI on the value being non-zero. The first client render also returns 0 for the duration of the first measurement window, then jumps to a real number on the next tick. If you use it for adaptive rendering, default the "high-fidelity" path until the first measurement comes in.

4. useDevicePixelRatio — Drawing at the Right Resolution

Canvas elements have two sizes: their CSS size, which is what determines how big the element looks on the page, and their pixel buffer size, which is what determines how detailed it looks. On a Retina display the device pixel ratio is 2, which means a <canvas width="600" height="400"> element sized at 600px × 400px in CSS will look fuzzy — the 600×400 pixel buffer is being stretched across 1200×800 physical pixels by the browser's compositor. The fix is to size the buffer at cssWidth × dpr and cssHeight × dpr, then scale the drawing context by dpr so your coordinates stay in CSS units.

useDevicePixelRatio tracks the current pixel ratio reactively — including when the user drags the window between a Retina laptop screen and an external 1x monitor:

import { useRef, useEffect } from 'react';
import { useDevicePixelRatio } from '@reactuses/core';

function CrispCanvas({ width, height, draw }: {
  width: number;
  height: number;
  draw: (ctx: CanvasRenderingContext2D, w: number, h: number) => void;
}) {
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const { pixelRatio } = useDevicePixelRatio();

  useEffect(() => {
    const canvas = canvasRef.current;
    if (!canvas) return;
    canvas.width = width * pixelRatio;
    canvas.height = height * pixelRatio;
    const ctx = canvas.getContext('2d')!;
    ctx.scale(pixelRatio, pixelRatio);
    draw(ctx, width, height);
  }, [width, height, pixelRatio, draw]);

  return (
    <canvas
      ref={canvasRef}
      style={{ width, height }}
    />
  );
}

Three lines of imperative setup, but they are the three lines almost every canvas-in-React tutorial gets wrong: set the buffer size to css × dpr, set the CSS size to the original dimensions via inline style, scale the context. The hook makes the third dependency — pixel ratio — reactive, so dragging the window between monitors triggers a redraw at the right density.

Internally the hook uses matchMedia on a (resolution: <ratio>dppx) query for the current ratio, plus the standard one for <ratio>dpr. When the ratio changes, the matchMedia listener fires, the hook re-renders, and your effect runs with the new value. The listener is added once on mount and removed on unmount — same lifetime story as everything else in this post.

The same pattern applies to anything drawing pixels: image canvases, WebGL contexts, video frame extraction. It also matters for <img> srcset selection, but the browser handles that automatically; you only need the hook when you are doing the rendering yourself. SSR returns 1 so layout calculations stay sensible on the server, and the value updates on the first paint after hydration.

5. useUpdate — A Re-Render, With No State

The strangest hook in this list and the one you reach for least often. useUpdate returns a stable function that, when called, forces a re-render of the component:

import { useRef } from 'react';
import { useUpdate, useRafFn } from '@reactuses/core';

function StopwatchDisplay() {
  const startRef = useRef(performance.now());
  const update = useUpdate();

  useRafFn(() => {
    update();
  });

  const elapsed = ((performance.now() - startRef.current) / 1000).toFixed(2);
  return <div>{elapsed}s</div>;
}

That stopwatch updates every frame without storing the elapsed time in React state. The source of truth is performance.now(), read fresh on every render; useUpdate exists only to schedule the render. Six lines, no setState, no closure over a stale time. You can do the same with a useState((s) => s + 1) but the intent is clearer with useUpdate — "render this thing again" rather than "increment a counter for the side effect of rendering this thing again".

The more pragmatic uses are for interop with imperative APIs that mutate values React does not track. A WebGL renderer that exposes its current camera position by reference; a Three.js scene graph; a Set or Map you are using as state without re-creating it on every change. After mutating, you call update() to tell React the component is dirty:

function FavoritesList({ favorites }: { favorites: Set<string> }) {
  const update = useUpdate();

  return (
    <ul>
      {[...favorites].map((id) => (
        <li key={id}>
          {id}{' '}
          <button onClick={() => {
            favorites.delete(id);
            update();
          }}>
            remove
          </button>
        </li>
      ))}
    </ul>
  );
}

Mutating the Set directly and then re-rendering is faster than the idiomatic setFavorites(new Set([...favorites].filter(x => x !== id))) for large sets, and lets the Set reference stay stable across renders so memoized children downstream do not have to recompute. It is also a perfectly good way to shoot yourself in the foot — React's optimizations assume immutability, so any place that relied on a reference change to detect an update will silently fail. Use it deliberately, document it loudly, and stick to plain useState whenever the perf cost is not measurable.

useUpdate also pairs with useTextSelection and other hooks that work with mutable platform objects (the post on event hooks covers that case). If the underlying object is the same reference call to call, setState is a no-op; useUpdate is the workaround.

Putting It Together: A 60fps Spring-Following Cursor

Four of the five hooks at once. A custom cursor that follows the real one with a spring, draws at the right resolution on Retina, shows its own FPS in the corner, pauses when the tab is hidden:

import { useRef } from 'react';
import {
  useRafFn,
  useRafState,
  useFps,
  useDevicePixelRatio,
  useEventListener,
} from '@reactuses/core';

function SpringCursor() {
  const target = useRef({ x: 0, y: 0 });
  const [pos, setPos] = useRafState({ x: 0, y: 0 });
  const velocity = useRef({ x: 0, y: 0 });
  const fps = useFps();
  const { pixelRatio } = useDevicePixelRatio();

  useEventListener('mousemove', (e: MouseEvent) => {
    target.current = { x: e.clientX, y: e.clientY };
  });

  useRafFn(() => {
    const dx = target.current.x - pos.x;
    const dy = target.current.y - pos.y;
    const stiffness = 0.15;
    const damping = 0.7;
    velocity.current.x = velocity.current.x * damping + dx * stiffness;
    velocity.current.y = velocity.current.y * damping + dy * stiffness;
    setPos({
      x: pos.x + velocity.current.x,
      y: pos.y + velocity.current.y,
    });
  });

  useEventListener('visibilitychange', () => {
    if (document.hidden) velocity.current = { x: 0, y: 0 };
  });

  const size = 24;
  return (
    <>
      <div
        style={{
          position: 'fixed',
          left: pos.x,
          top: pos.y,
          width: size,
          height: size,
          marginLeft: -size / 2,
          marginTop: -size / 2,
          borderRadius: '50%',
          background: 'currentColor',
          pointerEvents: 'none',
          imageRendering: pixelRatio >= 2 ? 'auto' : 'pixelated',
        }}
      />
      <div style={{ position: 'fixed', top: 8, left: 8, fontFamily: 'monospace' }}>
        {fps} fps @ {pixelRatio}x
      </div>
    </>
  );
}

Four hooks, each carrying their share of the work. useEventListener reads mouse coordinates at native rate into a ref — no React render. useRafFn runs the spring integration once per frame, reading the latest target and writing the spring position. useRafState batches the per-frame position update into a single render. useFps reports back what frame rate you are hitting. useDevicePixelRatio informs an image-rendering choice (small detail, but exactly the kind of thing that gets forgotten until someone on a 1x monitor complains).

The naive version of the same component would either call setState on every mousemove (renders at 500Hz, costs battery), or run a setInterval(handler, 16) that drifts and keeps running in the background tab, or skip the spring entirely and feel cheap. With the hooks it reads at the rate of the question — once per frame — and the React tree never re-renders faster than the user can see.

When to Reach for Which

You want to	Use
Run a callback every animation frame	`useRafFn`
Update state at most once per paint	`useRafState`
Measure the current frame rate	`useFps`
Draw at the display's native resolution	`useDevicePixelRatio`
Re-render after mutating something React does not track	`useUpdate`

Two non-rules. useRafFn is not a setInterval replacement — it runs at the display's refresh rate, which is 120Hz on a ProMotion display and 30Hz on a power-saving tab. If you need exactly-N-times-per-second timing, use useInterval and accept the visual cost. And useUpdate is the escape hatch — if you are reaching for it more than once or twice in a codebase, the underlying problem is usually "I am storing state outside React for performance reasons", and the right fix is to fix the perf reason, not normalize the escape hatch.

Installation

npm install @reactuses/core
# or
pnpm add @reactuses/core
# or
yarn add @reactuses/core

All five hooks tree-shake individually — importing useRafState does not pull in useDevicePixelRatio. Each ships TypeScript types and works in both client-rendered apps and SSR frameworks (Next.js, Remix, Astro); the loop-based hooks no-op on the server and useDevicePixelRatio / useFps return safe defaults (1 and 0 respectively) until hydration.

Related Hooks

If you find yourself wanting a render-loop hook that is not in this list, three adjacent posts are worth a look. The ref escape hatch covers useLatest — the internal trick that lets useRafFn see fresh closure values without restarting its loop — and is the post to read if you want to understand how these hooks work rather than just use them. Event hooks covers useEventListener and useThrottleFn, which fit naturally with useRafFn for input-driven animation. And scroll effects covers scroll-linked animation hooks that build on these primitives at a higher level.

Browse the full set at reactuse.com, or open one of the hooks above and read the source — most of these are under 40 lines, and the loop primitives at the bottom of all five are the same eight-line useRef + useEffect pattern you have probably already written half a dozen times.

Taming DOM Events in React: useEventListener, useEventEmitter, useKeyModifier, useTextSelection, useDebounceFn, useThrottleFn

reactuse.com — Tue, 26 May 2026 09:21:45 +0000

Taming DOM Events in React: useEventListener, useEventEmitter, useKeyModifier, useTextSelection, useDebounceFn, useThrottleFn

The DOM event model and the React render model do not get along. addEventListener wants a stable function reference; React hands you a new closure on every render. setTimeout-backed debounces want to outlive a frame; React reaches in and unmounts the component while the timer is still running. The keyboard tells you a key went down with one event and back up with another, but if the user alt-tabs in between, the up event never arrives and your "Shift is held" flag is stuck on true forever. The Selection API does not even fire selectionchange reliably on the same Selection object — it mutates the existing one and expects you to notice.

Every codebase ends up with the same patches for these. A useEffect that adds and removes a listener. A lodash debounce inside a ref. A keydown/keyup reducer with an Alt+Tab workaround that nobody quite remembers writing. The patches work. They are also five lines of intent buried under twenty lines of cleanup, and the cleanup is exactly where the bugs live.

ReactUse ships six small event hooks that fold the cleanup into the hook itself. This post walks each one: the bug in the naive version, what the hook does instead, and a component you would actually write with it. If you read the post on the ref escape hatch, the pattern will be familiar — every hook in this list closes over its callback through useLatest so the listener stays stable even as the function identity changes.

The Bug, in One useEffect

A search box that fetches results when the user types:

function SearchBox({ onResults }: { onResults: (rows: Row[]) => void }) {
  const [query, setQuery] = useState('');

  useEffect(() => {
    const id = setTimeout(async () => {
      const rows = await search(query);
      onResults(rows);
    }, 300);
    return () => clearTimeout(id);
  }, [query, onResults]);

  return <input value={query} onChange={(e) => setQuery(e.target.value)} />;
}

Three things wrong, and you have seen all of them. First, onResults is in the dependency array, so any parent that passes a new arrow function rebuilds the timeout on every render — the debounce window resets every keystroke, never fires, and nobody notices in dev because their parent happens to memoize. Second, if the component unmounts while the timeout is pending, the clearTimeout fires but the in-flight search() keeps running and calls onResults after the component is gone — a setState after unmount warning two levels up. Third, the cleanup runs on every dep change, not just unmount, so if query is "reactus" then "reactuse", you fire two requests with no guarantee that the second resolves second.

Each of those is fixable in one line. useDebounceFn bundles all three lines into the hook and leaves the component looking like the version you would draw on a whiteboard.

1. useEventListener — addEventListener, Without the Leak

useEventListener is the smallest hook in this post and the one you will reach for most often. It attaches a listener to a target — window, document, a ref, a function returning an element — and removes it when the component unmounts or the target changes.

import { useRef } from 'react';
import { useEventListener } from '@reactuses/core';

function GlobalShortcuts({ onCmdK }: { onCmdK: () => void }) {
  useEventListener('keydown', (e) => {
    if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
      e.preventDefault();
      onCmdK();
    }
  });
  return null;
}

No element argument means the default target is window — exactly what you want for a global keyboard shortcut. The handler is wrapped in useLatest internally, so onCmdK is read fresh on every event without re-binding the listener. Pass a brand-new arrow function on every render and the actual DOM listener still binds once, on mount.

A ref-targeted variant looks the same:

function VideoControls({ videoRef }: { videoRef: React.RefObject<HTMLVideoElement> }) {
  const [time, setTime] = useState(0);

  useEventListener('timeupdate', () => {
    if (videoRef.current) setTime(videoRef.current.currentTime);
  }, videoRef);

  return <div>{time.toFixed(1)}s</div>;
}

Two implementation details are worth knowing. The hook accepts the target as a ref, a node, or a function that returns one — the BasicTarget protocol shared by most ReactUse element hooks — which means you can wire a listener to an element you do not own yet, such as one rendered by a child via forwardRef. And the listener options argument (third positional, fourth named) is deep-compared, not reference-compared, so { passive: true } written inline does not cause a re-bind on every render the way a raw addEventListener call would.

The one thing the hook does not do is unwrap synthetic events. It is a thin wrapper around addEventListener and gives you the raw DOM event, not a React SyntheticEvent. That is intentional — most use cases for the hook are window or document listeners, where React's synthetic system does not reach anyway.

2. useEventEmitter — Pub-Sub Between Components, Without Context

Most cross-component event problems get solved with React context or a global store. Both are right answers most of the time, but neither fits the case where you want a transient notification — "the user just saved the form, show a toast somewhere" — without making the toast component re-render every time the form state changes.

useEventEmitter gives you a typed pub-sub primitive scoped to whatever component creates it:

import { useEventEmitter } from '@reactuses/core';

type ToastEvent = { kind: 'success' | 'error'; message: string };

function App() {
  const [event, fire] = useEventEmitter<ToastEvent>();

  return (
    <ToastContext.Provider value={{ event, fire }}>
      <Form />
      <ToastViewport />
    </ToastContext.Provider>
  );
}

function Form() {
  const { fire } = useContext(ToastContext);
  return (
    <button onClick={() => fire({ kind: 'success', message: 'Saved' })}>
      Save
    </button>
  );
}

function ToastViewport() {
  const { event } = useContext(ToastContext);
  const [toasts, setToasts] = useState<ToastEvent[]>([]);

  useEffect(() => {
    const sub = event((toast) => {
      setToasts((ts) => [...ts, toast]);
      setTimeout(() => setToasts((ts) => ts.slice(1)), 3000);
    });
    return () => sub.dispose();
  }, [event]);

  return <div className="toasts">{toasts.map((t, i) => <Toast key={i} {...t} />)}</div>;
}

Three things to notice. The hook returns a tuple — [event, fire, dispose] — and event is the subscribe function, not a data field. Calling event(listener) returns a { dispose } handle, the same shape as vscode.Disposable. The fire function takes one or two positional arguments and broadcasts to every listener synchronously; the broadcast is a copy-on-iterate loop, so a listener that unsubscribes itself during the call does not skip neighbors. And dispose() removes all listeners at once — useful when the emitter lives on a context that itself is about to unmount.

The pattern beats context-with-state when the receiver does not need to re-render unless an event arrives. A pure useEffect(() => event(listener), [event]) subscription means the toast viewport renders only when a toast comes in, not on every keystroke in the form. If you have ever profiled a flame graph and found a top-level context provider rerendering everything in the app, this is the hook you replace it with for the "fire-and-forget notification" cases.

There is a subtle quirk: the emitter is created with useRef, so it is stable across renders of the component that owns it — you can put it in a dependency array safely. But it is not shared between sibling components unless you put it on a context or pass it as a prop. Sharing across the whole app is a one-time useEventEmitter at the root plus a context provider; sharing within a subtree is whatever scope you choose.

3. useKeyModifier — Modifier State That Stays in Sync

The naive way to track whether Shift is currently held:

const [shift, setShift] = useState(false);
useEffect(() => {
  const down = (e: KeyboardEvent) => { if (e.key === 'Shift') setShift(true); };
  const up = (e: KeyboardEvent) => { if (e.key === 'Shift') setShift(false); };
  window.addEventListener('keydown', down);
  window.addEventListener('keyup', up);
  return () => {
    window.removeEventListener('keydown', down);
    window.removeEventListener('keyup', up);
  };
}, []);

This works in the demo and breaks in three places. The user holds Shift, alt-tabs to another window, releases Shift outside the page — the keyup never fires and your flag is stuck on true. The user holds Shift, then clicks something — the click handler runs with stale Shift state because keydown updates the state asynchronously. And on macOS, the OS sometimes swallows the keyup after a Command+Shift+key shortcut, leaving both Cmd and Shift "held" until the next keypress.

useKeyModifier sidesteps all three by reading KeyboardEvent.getModifierState() from every event the user produces — mousedown, mouseup, keydown, keyup — rather than maintaining its own bookkeeping:

import { useKeyModifier } from '@reactuses/core';

function FileList({ files }: { files: File[] }) {
  const shift = useKeyModifier('Shift');
  const meta = useKeyModifier('Meta');
  const [selected, setSelected] = useState<Set<string>>(new Set());

  function toggle(name: string) {
    setSelected((prev) => {
      const next = meta ? new Set(prev) : new Set();
      if (shift) /* range-select against last anchor */;
      next.has(name) ? next.delete(name) : next.add(name);
      return next;
    });
  }

  return (
    <ul>
      {files.map((f) => (
        <li
          key={f.name}
          className={selected.has(f.name) ? 'selected' : ''}
          onClick={() => toggle(f.name)}
        >
          {f.name}
        </li>
      ))}
    </ul>
  );
}

The hook accepts any of the 12 standard KeyboardEvent.getModifierState keys — Alt, AltGraph, CapsLock, Control, Fn, FnLock, Meta, NumLock, ScrollLock, Shift, Symbol, SymbolLock. The state updates on the same events the user is already producing, so the click handler that fires immediately after a keydown sees the up-to-date modifier value. And because the source of truth is getModifierState() rather than your own keydown/keyup pair, the alt-tab problem disappears: the next event the user produces re-reads the real OS state and you converge.

The default events the hook listens on are mousedown, mouseup, keydown, keyup. You can pass a smaller set if you have a specific case — events: ['mousedown', 'mouseup'] for a UI that only cares about modifier state at click time, for instance — but the default is the right one almost always. The cost of an empty listener is negligible.

4. useTextSelection — Observe Selection Without the Loop

The Selection API is one of the older DOM features and it shows. document.getSelection() returns the same Selection object every call, then mutates it in place when the user changes their selection. The selectionchange event fires on every mutation, including the intermediate ones while the user is dragging — sixty events per second on a fast machine, each of which returns the same object reference, so a naive useState(document.getSelection()) does not re-render because React sees the same value.

useTextSelection handles both halves of that:

import { useTextSelection } from '@reactuses/core';

function HighlightToolbar() {
  const selection = useTextSelection();
  const text = selection?.toString() ?? '';

  if (!text) return null;

  const range = selection!.getRangeAt(0);
  const rect = range.getBoundingClientRect();

  return (
    <div
      className="toolbar"
      style={{
        position: 'fixed',
        top: rect.top - 40,
        left: rect.left + rect.width / 2,
        transform: 'translateX(-50%)',
      }}
    >
      <button onClick={() => navigator.clipboard.writeText(text)}>Copy</button>
      <button onClick={() => share(text)}>Share</button>
    </div>
  );
}

The hook does two things to make this work. First, it listens to selectionchange on the document via useEventListener, so the cleanup is handled. Second, it pairs setState with a useUpdate() force-render — because document.getSelection() returns the same object every time, the useState setter shortcuts out and the toolbar does not re-render to the new range. The force-update is the workaround for an API older than React itself; the hook hides it so your component reads as if Selection were a normal immutable value.

Two practical notes. The hook does not give you the rendered range — you have to call selection.getRangeAt(0).getBoundingClientRect() yourself if you want pixel coordinates, which is what the example does. And the Selection API works on contenteditable elements and ordinary prose alike; if you are building a highlighter for a long-form reader (Medium-style), this is the primitive. If you are building a rich-text editor with structured ranges, you probably want a higher-level library like ProseMirror or Lexical — useTextSelection is a window onto the platform, not a replacement for editor state.

5. useDebounceFn — Function-Level Debounce That Cleans Up on Unmount

useDebounceFn wraps lodash's debounce in a React-aware shell:

import { useDebounceFn } from '@reactuses/core';

function SearchBox({ onResults }: { onResults: (rows: Row[]) => void }) {
  const [query, setQuery] = useState('');

  const { run } = useDebounceFn(async (q: string) => {
    const rows = await search(q);
    onResults(rows);
  }, 300);

  return (
    <input
      value={query}
      onChange={(e) => {
        setQuery(e.target.value);
        run(e.target.value);
      }}
    />
  );
}

Three things to notice against the earlier broken version. The handler is created once via useMemo keyed on wait and options, so identity is stable across renders; onResults is not a dependency because the hook reads it through useLatest internally. The returned { run, cancel, flush } object exposes the same interface as lodash's debounced function, so you can flush a pending call (on form submit, for example) or cancel it (on route change) without reaching into the timer yourself. And the hook registers useUnmount(() => debounced.cancel()), so a pending timeout never fires after the component is gone — no stale-state warnings, no setState on unmounted component.

The options argument passes through to lodash: { leading: true, trailing: false, maxWait: 1000 } and so on. The defaults — leading: false, trailing: true — are what you want for the search-as-you-type case. For a "save draft every N seconds, no matter what" pattern, maxWait is the option you want; the trailing-only default would let a continuously-typing user delay the save indefinitely.

One thing the hook intentionally does not solve: in-flight request ordering. If you fire two debounced searches and the slower one resolves second, the older response will overwrite the newer. That is an AbortController concern, not a debounce concern — pair useDebounceFn with a per-call AbortController if you need cancellation of the underlying request, not just the underlying timer.

6. useThrottleFn — At Most Once Per N Milliseconds

useDebounceFn says "wait until the user stops doing the thing, then act". useThrottleFn says "act now, but at most once per N milliseconds". The two get confused; they solve different problems.

import { useThrottleFn } from '@reactuses/core';

function ScrollSpy({ onSection }: { onSection: (id: string) => void }) {
  const { run } = useThrottleFn(() => {
    const current = nearestSection();
    if (current) onSection(current);
  }, 100);

  useEventListener('scroll', run, () => window, { passive: true });
  return null;
}

useThrottleFn takes the same shape as useDebounceFn — (fn, wait?, options?) returning { run, cancel, flush } — and the same internal hygiene: stable identity, latest-ref callback, cancel on unmount. The behavioral difference is in lodash.throttle: by default both leading and trailing edges fire, so the first scroll event runs immediately (no perceptible lag) and the last one runs at the end of the throttle window (no missed final position).

Use throttle for continuous streams where you want regular sampling — scroll position, mouse coordinates, resize handlers driving expensive layout reads. Use debounce for "tell me when the user has paused" — search input, autosave, validation. A common bug is reaching for debounce on a scroll listener; the user keeps scrolling, the trailing edge never fires until they stop, and your scroll-linked progress bar sits at zero until they let go.

A nuance about combining useEventListener and useThrottleFn: the example above passes run directly as the event handler, and that is correct because run is the throttled function. Be careful not to pass the inner callback by mistake — the throttle only applies if you call the wrapper.

Putting It Together: A Keyboard-Aware Selection Toolbar

A small component that uses four of these hooks at once. A floating toolbar appears over any text the user selects, the copy button skips the clipboard prompt when the user holds Shift (to copy as plain text), the position updates at most every 16 ms on scroll, and a global emitter broadcasts the copied text to anyone listening:

import { useState, useContext } from 'react';
import {
  useTextSelection,
  useKeyModifier,
  useEventListener,
  useThrottleFn,
  useEventEmitter,
} from '@reactuses/core';

type CopyEvent = { text: string; plain: boolean };
const CopyContext = React.createContext<ReturnType<typeof useEventEmitter<CopyEvent>> | null>(null);

function SelectionRoot({ children }: { children: React.ReactNode }) {
  const emitter = useEventEmitter<CopyEvent>();
  return <CopyContext.Provider value={emitter}>{children}{<SelectionToolbar />}</CopyContext.Provider>;
}

function SelectionToolbar() {
  const selection = useTextSelection();
  const shift = useKeyModifier('Shift');
  const ctx = useContext(CopyContext);
  const [rect, setRect] = useState<DOMRect | null>(null);

  const { run: updateRect } = useThrottleFn(() => {
    if (selection && selection.toString()) {
      setRect(selection.getRangeAt(0).getBoundingClientRect());
    } else {
      setRect(null);
    }
  }, 16);

  useEventListener('scroll', updateRect, () => window, { passive: true });

  React.useEffect(updateRect, [selection]);

  const text = selection?.toString() ?? '';
  if (!text || !rect || !ctx) return null;
  const [, fire] = ctx;

  return (
    <div
      className="floating-toolbar"
      style={{
        position: 'fixed',
        top: rect.top - 40,
        left: rect.left + rect.width / 2,
        transform: 'translateX(-50%)',
      }}
    >
      <button
        onClick={async () => {
          if (shift) {
            await navigator.clipboard.writeText(text);
          } else {
            await navigator.clipboard.write([
              new ClipboardItem({ 'text/html': new Blob([text], { type: 'text/html' }) }),
            ]);
          }
          fire({ text, plain: shift });
        }}
      >
        Copy {shift ? '(plain)' : ''}
      </button>
    </div>
  );
}

Five hooks, each line of caller code corresponding to one specific behavior. The equivalent component without them is roughly 80 lines once you have written the scroll listener cleanup, the selectionchange same-object workaround, the shift-key keydown/keyup reducer, the throttle, and the cross-component notification. That ratio — twenty lines of intent vs eighty lines of plumbing — is the case for picking up the library instead of repeating the workaround in every codebase.

When to Reach for Which

You want to	Use
Attach a DOM listener with automatic cleanup	`useEventListener`
Broadcast a transient event between components	`useEventEmitter`
Know whether Shift / Ctrl / Alt / Meta is held	`useKeyModifier`
Observe the user's current text selection	`useTextSelection`
Wait for the user to pause before running a function	`useDebounceFn`
Sample a continuous event at most once per N ms	`useThrottleFn`

Two non-rules. If you want a value that debounces — for example a query string that lags the input by 300 ms — reach for useDebounce (state version) rather than useDebounceFn (function version). Same for throttle. The Fn variants are for callbacks; the bare names are for state values. And if you find yourself reaching for useEventEmitter to broadcast something that already lives in state, you probably want context with a useReducer instead — the emitter is for transient signals, not state synchronization.

Installation

npm install @reactuses/core
# or
pnpm add @reactuses/core
# or
yarn add @reactuses/core

All six hooks tree-shake individually — importing useEventListener does not pull in useTextSelection. Each ships TypeScript types and works in both client-rendered apps and SSR frameworks (Next.js, Remix, Astro); the listeners that need a DOM no-op on the server, and the hooks return safe defaults until hydration.

Related Hooks

If event handling is your bottleneck, two adjacent ReactUse posts are worth a read. The ref escape hatch covers useLatest and useEvent, the primitives that almost every hook in this list uses internally to stay closure-safe — understanding them makes the source much easier to read. Pointer and gesture hooks covers useHover, useLongPress, useDoubleClick, and useClickOutside, which all share the same "ref-targeted listener with latest-ref callback" pattern in their internals.

Browse the full set at reactuse.com, or open one of the hooks above and read the source — most are under 50 lines, and you will probably find one or two you have been re-implementing in your own codebase for years.

React Pointer Hooks: Hover, Long-Press, Double-Click, Scratch, and Click-Outside Without the Bugs

reactuse.com — Mon, 25 May 2026 01:47:37 +0000

React Pointer Hooks: Hover, Long-Press, Double-Click, Scratch, and Click-Outside Without the Bugs

Pointer events are the part of React nobody writes about because everybody assumes they have already been figured out. They have not. The standard answers — onMouseEnter, onClick, a setTimeout for double-click, a window listener for click-outside — all work in the demo and all break in production. They flicker as the cursor crosses a child element. They fire an iOS ghost click 300 ms after a touch ends. They miss elements rendered through a portal. They count a double-click as two single-clicks because the second click handler runs before the first one is cancelled.

The DOM event model is what it is. Browsers ship different gesture pipelines on mobile and desktop, the spec for dblclick is older than React, and composedPath() is the only reliable way to walk a click out through shadow boundaries and portals. None of that is going to change. What you can change is whether every component in your app re-implements the workarounds from scratch.

ReactUse ships six small pointer hooks that close the gaps. This post walks each one: the bug in the naive version, what the hook does instead, and a concrete component you would actually build with it. If you read the post on the ref escape hatch, one detail will look familiar — most of these hooks use useLatest internally so that the listener stays stable even as the callback identity moves.

Why Pointer Events Are a Swamp

A two-line example. A dropdown that closes when you click outside it:

function Dropdown() {
  const [open, setOpen] = useState(false);
  const ref = useRef<HTMLDivElement>(null);

  useEffect(() => {
    function handler(e: MouseEvent) {
      if (ref.current && !ref.current.contains(e.target as Node)) {
        setOpen(false);
      }
    }
    document.addEventListener('mousedown', handler);
    return () => document.removeEventListener('mousedown', handler);
  }, []);

  return <div ref={ref}>{open && <Menu />}</div>;
}

Four things wrong with this. First, no touchstart listener, so it does not close on mobile. Second, contains does not cross portals — if <Menu /> renders into document.body, clicking the menu items closes the menu. Third, the listener uses the bare Element.contains check instead of composedPath(), so anything inside a shadow root inside the dropdown is treated as outside. Fourth, the handler captures the initial setOpen closure; if the parent passes a new onClose prop, the listener still calls the old one because the effect only re-binds on mount.

Each of those is a one-line fix. Each of those one-line fixes is what makes the hook below 25 lines instead of 5. That is the whole pitch.

1. useHover — Hover State That Does Not Flicker

useHover returns a boolean for whether the cursor is currently inside a target element. The signature is exactly what you would write yourself:

import { useRef } from 'react';
import { useHover } from '@reactuses/core';

function Tooltip({ children, label }: { children: React.ReactNode; label: string }) {
  const ref = useRef<HTMLDivElement>(null);
  const hovered = useHover(ref);

  return (
    <div ref={ref} style={{ position: 'relative', display: 'inline-block' }}>
      {children}
      {hovered && <div className="tooltip">{label}</div>}
    </div>
  );
}

Two details matter. The hook listens to mouseenter and mouseleave, not mouseover and mouseout. mouseover bubbles, which means the cursor crossing into any child element fires another event and you spend most of your time flickering between true and false if you are not careful. mouseenter does not bubble — it fires once when the cursor enters the bounding element and once when it leaves, regardless of how many children sit underneath. This is the same reason CSS :hover does not flicker on nested elements: the browsers built the right primitive, they just hid it behind a less-obvious event name.

The other detail is that useHover takes a target ref, not a callback ref. The hook resolves the target through ReactUse's BasicTarget helper, which means you can pass a ref, a DOM node, or a function that returns one — useful when the element comes from another hook like useDraggable.

2. useMousePressed — Pressed State, Plus Where the Press Came From

hovered tells you if the pointer is over the element. useMousePressed tells you if the pointer is down on it — distinguishing mouse, touch, and drag as separate sources so you can react differently to each.

import { useRef } from 'react';
import { useMousePressed } from '@reactuses/core';

function PressyButton({ children }: { children: React.ReactNode }) {
  const ref = useRef<HTMLButtonElement>(null);
  const [pressed, source] = useMousePressed(ref, { touch: true, drag: false });

  return (
    <button
      ref={ref}
      className={pressed ? 'pressed' : ''}
      data-source={source} // 'mouse' | 'touch' | null
    >
      {children}
    </button>
  );
}

Two values come back as a tuple: the boolean and a sourceType of 'mouse' | 'touch' | null. The source matters more than it looks. A touch press should not animate a hover-style transition because the user's finger is covering the element. A drag-start press should not trigger the button's onClick — you can use the source to decide whether to ignore the release. The hook handles the listener cleanup including the dragend and touchcancel paths that are easy to forget; if you have ever shipped a button that stayed in the "pressed" state because the user dragged off it, you have shipped the bug this hook closes.

There is a subtle thing about the listener targets too. mousedown is attached to the element, but mouseup and mouseleave are attached to the window. That is intentional: if the user presses on the button and releases outside it, you want to see the release. Attaching mouseup to the element itself misses that case — the button stays "pressed" until the user comes back and clicks it again.

3. useLongPress — Tap-and-Hold Without the iOS Ghost Click

A long-press is a tap held for a configurable duration before firing. The naive version is a setTimeout on mousedown cleared by mouseup:

function LongPressable({ onLongPress }: { onLongPress: () => void }) {
  const timer = useRef<number>();
  return (
    <div
      onMouseDown={() => { timer.current = window.setTimeout(onLongPress, 500); }}
      onMouseUp={() => clearTimeout(timer.current)}
    />
  );
}

That works on desktop. On iOS Safari, after the user lifts their finger from a long press, the OS fires a synthetic click event 300 ms later — the "ghost click" — which can trigger an unrelated handler on whatever element the finger landed on next. The fix is to attach a one-shot touchend listener with preventDefault to the element that was pressed, which is exactly the bookkeeping useLongPress does for you:

import { useLongPress } from '@reactuses/core';

function MessageBubble({ message }: { message: Message }) {
  const [showActions, setShowActions] = useState(false);

  const longPress = useLongPress(
    () => setShowActions(true),
    { delay: 500, isPreventDefault: true },
  );

  return (
    <div className="bubble" {...longPress}>
      {message.text}
      {showActions && <ActionSheet onClose={() => setShowActions(false)} />}
    </div>
  );
}

The hook returns an object of event handlers you spread onto the element — onMouseDown, onMouseUp, onMouseLeave, onTouchStart, onTouchEnd — so the listener wiring lives inside React's synthetic event system instead of a raw addEventListener. That matters because synthetic events get batched correctly with React's state updates; a long-press that opens a modal will not produce two extra renders the way a manual addEventListener would.

isPreventDefault defaults to true and is the setting you want for almost every use case except scrolling. The one case where you want it off: when the long-press target is something the user might also want to scroll past, like a list item where the long-press opens a context menu but a vertical swipe should still scroll the list.

4. useDoubleClick — One Click vs Two, Without the Race

The browser ships a dblclick event, but it fires in addition to two click events, not instead of them. If you wire up both onClick and onDoubleClick, every double-click also triggers two single-click handlers. The standard fix is a debounce window — count clicks, wait for the gap, then dispatch single or double based on the count:

import { useRef } from 'react';
import { useDoubleClick } from '@reactuses/core';

function FileRow({ file }: { file: File }) {
  const ref = useRef<HTMLDivElement>(null);

  useDoubleClick({
    target: ref,
    latency: 250,
    onSingleClick: () => selectFile(file),
    onDoubleClick: () => openFile(file),
  });

  return <div ref={ref} className="row">{file.name}</div>;
}

useDoubleClick takes a target plus two callbacks and a latency. Click once, wait latency ms; if nothing else arrives, it is a single click. Click twice within latency, it is a double-click and the single-click never fires. The default latency of 300 ms matches what most desktop file managers use; you can pull it down to 200 ms for snappier UI or push it up to 500 ms if you are building something for older users or touch-first interfaces.

The hook also calls preventDefault on touchend events to head off iOS's "double-tap to zoom" behavior, which would otherwise zoom the page when a user double-taps a list row. That is one of those defaults you do not notice until it is missing and a beta tester files a bug.

5. useClickOutside — Dismiss on Outside Click, Through Portals

useClickOutside (also exported as useClickAway for parity with the older API name) is the "dismiss when the user clicks anywhere else" hook. The naive contains check breaks on portals and shadow DOM; the hook uses composedPath() instead, which walks the full event path including across shadow boundaries and across portals into their logical parents.

import { useRef, useState } from 'react';
import { useClickOutside } from '@reactuses/core';

function Popover({ trigger, children }: { trigger: React.ReactNode; children: React.ReactNode }) {
  const [open, setOpen] = useState(false);
  const ref = useRef<HTMLDivElement>(null);

  useClickOutside(ref, () => setOpen(false));

  return (
    <div ref={ref} className="popover-root">
      <button onClick={() => setOpen((o) => !o)}>{trigger}</button>
      {open && <div className="popover-content">{children}</div>}
    </div>
  );
}

The hook listens to both mousedown and touchstart, not click. mousedown fires before mouseup and before click, which means the dropdown closes as soon as the press happens — before the click event would have triggered any handler on the element the user is pressing on. That feels right. If you listened to click instead, the click handler on the target would run before the dropdown closed, and if that handler also opened a modal, you would see the modal flash open and then the dropdown's close ripple through.

The third argument is an enabled boolean. Pass false when the menu is hidden to avoid running the listener at all — small thing, but if you have fifty dropdowns on a page you have fifty global mousedown listeners, and the cost adds up.

One thing to be aware of: the hook closes over handler through useLatest, so the listener stays stable even if you pass a new function on every render. That means you can write useClickOutside(ref, () => setOpen(false)) inline without worrying about the listener re-binding — same trick the ref escape hatch post covers in detail.

6. useScratch — Relative Pointer Position During a Drag

useScratch is the workhorse for any UI that needs to know where inside an element the pointer is during a drag — color pickers, signature pads, marquee selection, slider thumbs that need pixel-perfect tracking. The hook returns a state object containing the press's start position, the current position, the delta from the previous frame, and whether a scratch is in progress.

import { useRef } from 'react';
import { useScratch } from '@reactuses/core';

function ColorPicker() {
  const ref = useRef<HTMLDivElement>(null);
  const { x, y, isScratching } = useScratch(ref);

  const hue = x != null ? (x / 240) * 360 : 0;

  return (
    <div
      ref={ref}
      style={{
        width: 240,
        height: 24,
        background: 'linear-gradient(to right, red, yellow, lime, cyan, blue, magenta, red)',
        position: 'relative',
        cursor: 'crosshair',
      }}
    >
      {x != null && (
        <div
          style={{
            position: 'absolute',
            left: x - 2,
            top: 0,
            width: 4,
            height: 24,
            background: isScratching ? '#000' : '#444',
            pointerEvents: 'none',
          }}
        />
      )}
    </div>
  );
}

Two implementation details are worth knowing. First, the position updates run through useRafState so React re-renders at most once per animation frame — you can drag a finger across the element at 120 Hz and your component still renders at 60. Without rAF batching, a fast drag generates one render per mousemove, and on a high-DPI touchscreen that is hundreds per second.

Second, the hook attaches its mousemove and mouseup listeners to the document, not the element, while only mousedown is on the element. That is the same reason useMousePressed listens on the window — once the press starts, the drag can leave the original bounding box and you still want to track it. If the listeners were on the element, the user would only have to drag a few pixels outside before the gesture broke.

The callbacks — onScratch, onScratchStart, onScratchEnd — are read through a useLatest ref, so you can pass closures that capture component state without breaking memoization. Useful for the signature-pad pattern, where onScratch needs to draw onto a canvas using the latest strokeColor.

Putting It Together: A Context Menu

A small example that uses four of these hooks together. Long-press to open a context menu, the menu dismisses on outside click, the trigger shows a pressed state while the press is in progress, and the items in the menu support double-click to perform a "default action":

import { useRef, useState } from 'react';
import {
  useLongPress,
  useMousePressed,
  useClickOutside,
  useDoubleClick,
} from '@reactuses/core';

function ContextMenuItem({ label, onSelect }: { label: string; onSelect: () => void }) {
  const ref = useRef<HTMLLIElement>(null);
  useDoubleClick({
    target: ref,
    latency: 200,
    onSingleClick: () => {/* hover-equivalent: do nothing */},
    onDoubleClick: onSelect,
  });
  return <li ref={ref}>{label}</li>;
}

function ContextTarget({ items }: { items: Array<{ label: string; onSelect: () => void }> }) {
  const triggerRef = useRef<HTMLDivElement>(null);
  const menuRef = useRef<HTMLUListElement>(null);
  const [open, setOpen] = useState(false);

  const [pressed] = useMousePressed(triggerRef, { drag: false });
  const longPress = useLongPress(() => setOpen(true), { delay: 400 });

  useClickOutside(menuRef, () => setOpen(false), open);

  return (
    <>
      <div
        ref={triggerRef}
        className={`target ${pressed ? 'pressed' : ''}`}
        {...longPress}
      >
        Hold me
      </div>
      {open && (
        <ul ref={menuRef} className="menu">
          {items.map((item) => (
            <ContextMenuItem key={item.label} {...item} />
          ))}
        </ul>
      )}
    </>
  );
}

Four hooks, each ten lines of caller code. The equivalent component without them is roughly 120 lines once you have handled the iOS ghost click, the portal-aware click-outside, the rAF-batched pressed state, and the single-vs-double dispatch. That ratio — ten lines of intent vs a hundred lines of plumbing — is the case for picking up the library instead of pasting the same workaround into ten components.

When to Reach for Which

You want to react to	Use
Cursor entering / leaving an element	`useHover`
Pointer is currently down on an element	`useMousePressed`
Tap-and-hold for `N` ms (especially on mobile)	`useLongPress`
Single vs double click with no double-fire	`useDoubleClick`
Click anywhere outside an element (dropdown, modal, popup)	`useClickOutside`
Where inside an element a drag is happening	`useScratch`

Two non-rules. If you want a draggable element that moves with the pointer (a panel, a sticky note), reach for useDraggable instead — useScratch gives you coordinates but does not move the element. And if you want focus, not press, use useFocus or useActiveElement; a "pressed" button and a "focused" button are different things and you usually want both.

Installation

npm install @reactuses/core
# or
pnpm add @reactuses/core
# or
yarn add @reactuses/core

All six hooks tree-shake individually — importing useHover does not pull in useScratch. Each ships TypeScript types and works in both client-rendered apps and SSR frameworks (Next.js, Remix, Astro); the listeners that need a DOM no-op on the server, and the hooks return safe defaults until hydration.

Related Hooks

If pointer interactions are your bottleneck, two adjacent ReactUse posts are worth a read. Observer hooks covers useIntersectionObserver, useResizeObserver, and useMutationObserver — the right primitives when "user did X" should become "element is in state Y". The ref escape hatch post covers useLatest and useEvent, which are what every hook in this post uses internally to stay closure-safe; understanding them makes the source of these gesture hooks much easier to read.

Browse the full set at reactuse.com, or open one of the hooks above and read the source — most are under 40 lines, and you will probably find one or two you have been re-implementing in your own codebase for years.

The Ref Escape Hatch: React Hooks for Stale Closures, Stable Callbacks, and Force Updates

reactuse.com — Wed, 20 May 2026 07:20:58 +0000

The Ref Escape Hatch: React Hooks for Stale Closures, Stable Callbacks, and Force Updates

Every function component re-runs from scratch on every render, and every closure created during that render captures the props and state as they were at that moment. That is the whole React model in one sentence, and it is also the source of an entire family of bugs: the event handler that reads a stale count, the useEffect that re-subscribes on every render because its callback identity changed, the setState that fires after the component already unmounted. They look like different problems. They are all the same problem — a closure holding onto a snapshot that has moved on.

React's official answer to "I need a value that survives renders without being captured" is useRef. A ref is a mutable box whose identity never changes; reading ref.current always gives you the current value, not the one from when the closure was created. That is the escape hatch. The trouble is that wiring a ref up correctly — keeping it in sync, reading it at the right time, not breaking SSR — is fiddly enough that everyone writes a slightly different version, and some of those versions race.

ReactUse ships the productized versions. This post walks seven of them. None is more than a dozen lines of source; the value is that they are the correct dozen lines, the same in every project. If you read last week's post on specialized effect hooks, this is the companion piece: those hooks fix useEffect, these fix the closures that flow through it.

The Bug, Concretely

Here is a chat component that polls for unread messages and shows the count. It is wrong in a way that survives code review:

function Inbox({ userId }: { userId: string }) {
  const [count, setCount] = useState(0);

  useEffect(() => {
    const id = setInterval(() => {
      // BUG: `count` here is always 0 — the value captured when the
      // effect first ran. The interval never sees an updated count.
      console.log(`Polling, current count is ${count}`);
      fetchUnread(userId).then((n) => setCount(count + n));
    }, 5000);
    return () => clearInterval(id);
  }, [userId]); // count intentionally left out, or the interval resets every change

  return <Badge>{count}</Badge>;
}

The interval callback closes over count on the render where the effect ran. count was 0 then, so it is 0 forever inside that closure — setCount(count + n) is really setCount(0 + n). The usual "fixes" each trade one bug for another: add count to the deps and the interval tears down and rebuilds every five seconds; use the setCount((c) => c + n) updater and you have fixed the write but the console.log still lies, and any logic that needs to read the latest count outside a setter is still stuck.

What you actually want is: a stable interval that never resets, which can still read the latest count when it fires. That is a ref. The hooks below are refs with the ergonomics filled in.

1. useLatest — Always Read the Current Value

useLatest takes a value and returns a ref that always holds the most recent version of it. The ref's identity never changes, so anything that closes over the ref — an interval, an event listener, a long-lived callback — reads through it to today's value, not the one frozen at subscription time.

import { useLatest } from "@reactuses/core";

function Inbox({ userId }: { userId: string }) {
  const [count, setCount] = useState(0);
  const countRef = useLatest(count);

  useEffect(() => {
    const id = setInterval(() => {
      // countRef.current is always the latest count, even though
      // the effect ran exactly once.
      console.log(`Polling, current count is ${countRef.current}`);
      fetchUnread(userId).then((n) => setCount(countRef.current + n));
    }, 5000);
    return () => clearInterval(id);
  }, [userId]); // no `count` in deps — the interval is stable

  return <Badge>{count}</Badge>;
}

The effect depends only on userId, so the interval is created once and survives every count change. The read goes through countRef.current, which useLatest keeps current by writing to it in a layout effect on every render. This is the single most useful member of the family: any time you find yourself adding a value to a dependency array only so the closure can read it — and not because you want the effect to re-run — useLatest is the fix.

2. useEvent — A Stable Callback That Always Sees Fresh State

useLatest solves reading a value through a stable reference. useEvent solves the same problem for a function: it returns a callback whose identity is frozen for the component's lifetime, but which always invokes the latest version of the function you passed — with the latest props and state baked in.

This is the hook that lets you pass a handler to a memoized child without breaking its memoization:

import { useEvent } from "@reactuses/core";

function SearchBox({ onResults }: { onResults: (r: Result[]) => void }) {
  const [query, setQuery] = useState("");
  const [filters, setFilters] = useState<Filters>(defaultFilters);

  // Stable identity, but reads the latest query AND filters every call.
  const search = useEvent(() => {
    runSearch(query, filters).then(onResults);
  });

  // <ExpensiveButton> is React.memo'd. Because `search` never changes
  // identity, the button never re-renders on query/filter keystrokes.
  return (
    <>
      <input value={query} onChange={(e) => setQuery(e.target.value)} />
      <ExpensiveButton onClick={search}>Search</ExpensiveButton>
    </>
  );
}

Without useEvent, you reach for useCallback(() => runSearch(query, filters), [query, filters]) — which produces a new search on every keystroke, defeating React.memo on the button. Drop the deps to [] and the closure goes stale, searching for the empty initial query forever. useEvent gives you both: stable identity and fresh closure. If the name looks familiar, this is the same idea as React's experimental useEffectEvent / the old useEvent RFC — available today, no canary build required. Use it for event handlers and callbacks you pass downward; keep it out of dependency arrays where you actually want re-runs.

3. useMountedState — Don't setState After Unmount

The "Can't perform a React state update on an unmounted component" warning comes from an async operation resolving after the component is gone. The fix is a flag that flips on unmount, checked before every late setState. useMountedState is that flag, as a ref behind a getter:

import { useMountedState } from "@reactuses/core";

function UserCard({ id }: { id: string }) {
  const [user, setUser] = useState<User | null>(null);
  const isMounted = useMountedState();

  useEffect(() => {
    fetchUser(id).then((u) => {
      // The fetch may resolve after the user navigates away.
      if (isMounted()) setUser(u);
    });
  }, [id]);

  return user ? <Card user={user} /> : <Spinner />;
}

isMounted is a stable getter — calling it returns the current mount state from a ref, so you can call it inside any async callback without adding it to dependency arrays. It is deliberately a function and not a boolean: a boolean would itself be a stale snapshot. For fetches you can often prefer an AbortController, but useMountedState covers the cases an abort signal does not reach — timers, third-party promises, subscription callbacks.

4. usePrevious — Compare Against the Last Render

Sometimes you need the value from the previous render to decide what to do this one: animate in a direction based on whether a number went up or down, fire an effect only when a value actually changed from a specific old value, log transitions. usePrevious hands you exactly that:

import { usePrevious } from "@reactuses/core";

function Price({ value }: { value: number }) {
  const previous = usePrevious(value);
  const direction =
    previous === undefined ? "flat" : value > previous ? "up" : value < previous ? "down" : "flat";

  return <span className={`price price--${direction}`}>${value.toFixed(2)}</span>;
}

On the first render previous is undefined (there was no prior render), and on every render after, it holds the value from the render before. ReactUse's implementation tracks this with state updates during render rather than the naive "write a ref in an effect" approach — which matters because the effect-based version reports the wrong value during the render itself. Worth knowing what the hook does under the hood, but the point is you stop reimplementing it.

5. useFirstMountState — Know If This Is the First Render

A close cousin: instead of the previous value, you sometimes just need to know whether this is the very first render. useFirstMountState returns true on the initial render and false on every render after — synchronously, during render, before any effect runs.

import { useFirstMountState } from "@reactuses/core";

function Analytics({ route }: { route: string }) {
  const isFirstMount = useFirstMountState();

  useEffect(() => {
    // Distinguish the initial page load from later client-side navigations.
    track(isFirstMount ? "page_view_initial" : "page_view_spa", { route });
  }, [route]);

  return null;
}

This is the building block behind "skip the mount" effect hooks like useUpdateEffect — but exposed directly for when you want the boolean in render logic, not just in an effect. Because it reads during render (it does not wait for an effect), you can use it to choose initial styles, decide whether to animate, or branch JSX, none of which an effect-based "did mount" flag can do in time.

6. useUpdate — Force a Re-render on Demand

Refs are invisible to React's render cycle: mutating ref.current does not schedule a render. Usually that is the point. Occasionally you have state that genuinely lives outside React — a value on a ref, an external store, a mutable instance — and you need to tell React "something changed, paint again." useUpdate returns a function that does exactly one thing: force a re-render.

import { useUpdate, useLatest } from "@reactuses/core";

function StopwatchDisplay({ stopwatch }: { stopwatch: ExternalStopwatch }) {
  const update = useUpdate();

  useEffect(() => {
    // The stopwatch mutates its own elapsed time; it does not live in React state.
    // Subscribe and force a render on each tick so the display reflects it.
    return stopwatch.onTick(() => update());
  }, [stopwatch, update]);

  return <time>{stopwatch.elapsed}ms</time>;
}

update has a stable identity, so it is safe in dependency arrays and effect bodies. Reach for it sparingly — most "I need to force a render" instincts are better served by actual state — but for bridging an external mutable source into React's render cycle, it is the precise tool, and far clearer than the useReducer((x) => x + 1, 0) incantation people copy around.

7. useMergedRefs — Point Many Refs at One Node

The last one is a different flavor of ref problem: not staleness, but composition. A DOM node can only be handed to one ref prop, but you frequently have several consumers that each need it — your own measurement ref, a forwarded ref from a parent, and a library's ref (a drag handle, a focus trap, an intersection observer). useMergedRefs combines them into a single ref callback that fans the node out to all of them:

import { forwardRef, useRef } from "react";
import { useMergedRefs } from "@reactuses/core";

const Field = forwardRef<HTMLInputElement, FieldProps>(function Field(props, forwardedRef) {
  const localRef = useRef<HTMLInputElement>(null); // we want to measure/focus it ourselves
  const mergedRef = useMergedRefs(localRef, forwardedRef);

  // localRef.current and the parent's ref both point at the same input.
  return <input ref={mergedRef} {...props} />;
});

It handles both shapes of ref — object refs ({ current }) and callback refs ((node) => …) — and assigns the node to each. This removes the most tedious boilerplate in the React component library author's life: the hand-rolled setRef helper that every design system reinvents, usually without handling callback refs correctly.

Putting It Together

The opening Inbox bug, written with the toolbox instead of around it:

import { useLatest, useMountedState, useEvent } from "@reactuses/core";

function Inbox({ userId, onOpen }: { userId: string; onOpen: (id: string) => void }) {
  const [count, setCount] = useState(0);
  const countRef = useLatest(count);
  const isMounted = useMountedState();

  useEffect(() => {
    const id = setInterval(() => {
      fetchUnread(userId).then((n) => {
        if (isMounted()) setCount(countRef.current + n); // fresh count, no late update
      });
    }, 5000);
    return () => clearInterval(id);
  }, [userId]); // stable interval — never rebuilds on count change

  // Stable handler for a memoized row, always reading the latest count.
  const handleOpen = useEvent(() => {
    track("inbox_open", { unread: countRef.current });
    onOpen(userId);
  });

  return <InboxButton onClick={handleOpen} badge={count} />;
}

Three hooks, three classes of closure bug closed: a stable interval that reads fresh state (useLatest), no setState-after-unmount (useMountedState), and a stable handler that does not break the memoized child (useEvent). No dependency-array gymnastics, no setRef helper, no useReducer force-update trick.

Try Them Out

Each hook has a runnable demo on its docs page — open one, mutate the inputs, and watch what stays stable and what stays fresh:

Install with npm install @reactuses/core (or pnpm add @reactuses/core) and import directly. No provider, no peer dependencies beyond React 16.8+. The full hook list and source for everything above is at reactuse.com.

The mental model is the whole game: every render is a snapshot, closures capture the snapshot, and useRef is the door out. These seven hooks are the door, with the hinges already oiled.

Beyond useEffect: Specialized Effect Hooks for Async, Deep Comparisons, and SSR

reactuse.com — Tue, 19 May 2026 12:09:03 +0000

Beyond useEffect: Specialized Effect Hooks for Async, Deep Comparisons, and SSR

React gives you exactly one effect hook: useEffect. Every other effect pattern — running once after mount, skipping the first render, comparing object dependencies, handling async work without a race condition, running layout effects on the server without a warning — is something you have to assemble yourself. Most teams end up shipping the same five or six wrapper hooks in a utils/hooks.ts file. Different teams write subtly different versions of the same thing. Some of those versions are broken.

This is the kind of repetitive infrastructure that does not belong in your codebase. ReactUse ships the specialized effect hooks already — small, focused wrappers around useEffect and useLayoutEffect that close the most common gaps. This post walks each of nine of them: what useEffect makes awkward, what the hook does differently, and a concrete example of where it fits.

If you already use ReactUse for timers, observers, or browser APIs, you have already imported some of these without thinking about it. The point of going through them deliberately is to know what is in the toolbox before you write the wrapper one more time.

Why useEffect Alone Is Not Enough

Take a single line from a real component:

useEffect(() => {
  fetch(`/api/user/${id}`).then((r) => r.json()).then(setUser);
}, [id]);

That snippet has four problems on day one and a fifth one a month later:

No abort. If id changes mid-flight, the old request resolves after the new one and overwrites the newer data — the classic race condition.
No async/await. You cannot mark the effect callback async because React expects either undefined or a cleanup function, not a Promise. So every async effect either uses .then chains or wraps an IIFE.
No skip-on-mount option. Sometimes you want to react to id changing but not run the effect when the component first renders (the parent already gave you the initial data). Plain useEffect always runs at least once.
No deep compare on deps. If id is { workspace: "a", user: "b" }, every render produces a new object reference and the effect runs every time, even though nothing changed.
SSR + useLayoutEffect. A month later someone switches the component to use useLayoutEffect for some DOM measurement, and now SSR logs a warning on every page render.

Each of these is fixable, but the fix takes 5 to 30 lines and is easy to get subtly wrong. The hooks below close each gap directly.

1. useAsyncEffect — async/await Without the IIFE

The pattern everyone writes the first time:

useEffect(() => {
  let cancelled = false;
  (async () => {
    const r = await fetch(`/api/user/${id}`);
    const data = await r.json();
    if (!cancelled) setUser(data);
  })();
  return () => { cancelled = true; };
}, [id]);

That works. It is also six lines of boilerplate to do what async () => { setUser(await fetch(...).then((r) => r.json())); } would do if React allowed it. useAsyncEffect closes that gap:

import { useAsyncEffect } from "@reactuses/core";

useAsyncEffect(async () => {
  const r = await fetch(`/api/user/${id}`);
  setUser(await r.json());
}, [id]);

The hook accepts an async callback directly and ignores the Promise return value (no false-positive cleanup warning). It does not handle cancellation for you — that is the next hook's job, or a manual AbortController. Use useAsyncEffect when the async body is short and you do not need to bail out partway through. When you do need cancellation, wire up an AbortController:

useAsyncEffect(async (signal) => {
  const r = await fetch(`/api/user/${id}`, { signal });
  setUser(await r.json());
}, [id]);

The hook passes an AbortSignal as the first argument and aborts it on cleanup, so the in-flight request is cancelled instead of resolving into a stale state setter.

This single hook removes about 80% of the "I should have used a wrapper" moments in a typical codebase. Most data-fetching effects are short, async, and want to be cancelled on change. useAsyncEffect is exactly that.

2. useUpdateEffect — Skip the Mount

useEffect always runs after the first render. Sometimes that is wrong: if a component already received its initial value from props, running the effect on mount duplicates work or fires a "value changed" notification when nothing has actually changed yet.

The workaround in plain React is a ref:

const isFirst = useRef(true);
useEffect(() => {
  if (isFirst.current) { isFirst.current = false; return; }
  onChange(value);
}, [value]);

That works, but every team has at least three versions of this in their codebase. useUpdateEffect is the same thing as useEffect minus the first run:

import { useUpdateEffect } from "@reactuses/core";

useUpdateEffect(() => {
  onChange(value);
}, [value]);

The most common use case is controlled-component change notifications. You want to call onChange when the internal value updates, not when the parent first mounts the component with an initial value. The plain useEffect version fires on mount and the parent gets a spurious onChange(initialValue) before the user has done anything.

A second use case is analytics: "fire a viewed_filter event when the filter changes." The mount is not a change; it is the starting state.

3. useMount — The "Run Once on Mount" Idiom

useEffect(() => { /* ... */ }, []) is technically correct for "run once on mount." It is also visually noisy and a common lint-rule misfire (eslint's exhaustive-deps will complain if the callback closes over any variables, even when you genuinely mean "snapshot at mount").

useMount is a one-purpose alias that documents intent:

import { useMount } from "@reactuses/core";

useMount(() => {
  trackPageView();
  initialiseSentry();
});

Functionally identical to useEffect(fn, []), but the name is the documentation. When you see useMount, you know without reading the deps that the callback fires exactly once. When you see useEffect(fn, []), you have to scan the body to confirm there are no closed-over reactive variables that should have been in the deps.

4. useUnmount — Cleanup Without the Empty Effect

The mirror of useMount. The plain-React version of "do X on unmount" is:

useEffect(() => () => doCleanup(), []);

That parses as "the effect callback returns a cleanup function." It is correct, but the inner double arrow is the kind of thing nobody reads twice. useUnmount is the explicit version:

import { useUnmount } from "@reactuses/core";

useUnmount(() => {
  socket.close();
  flushAnalytics();
});

The hook captures the latest callback (via a ref internally) so you get the most recent values at unmount time, not the values from mount. That fixes a subtle bug in the plain-React version: if you write useEffect(() => () => doCleanup(value), []), value is captured at mount and the cleanup runs against stale data. useUnmount does not have that bug.

5. useDeepCompareEffect — When Your Deps Are Objects

React compares effect deps with Object.is. If the dep is an object or array, every parent re-render produces a new reference and the effect runs even though the contents are identical. The "fix" most teams reach for is JSON.stringify-ing the dep, which works for shallow data and breaks for anything with functions, Dates, or non-serializable values.

useDeepCompareEffect replaces Object.is with a structural deep equality check:

import { useDeepCompareEffect } from "@reactuses/core";

useDeepCompareEffect(() => {
  fetcher.run(query);
}, [query]); // query is { workspace: "a", filters: { ... } }

When the parent re-renders and produces a new query object with the same contents, the effect does not re-run. When the contents actually change, it does. The trade-off is that deep equality is O(n) on the dependency size — it is not free. Reach for it when you have a small object dep you cannot memoize at the source. If you can useMemo the dep, prefer that.

There is one trap: do not use useDeepCompareEffect with primitive-only deps. The hook throws if you pass [someString, someNumber] — for those, useEffect is the right tool, and the hook fails loudly so you do not silently slow down an effect that did not need it.

6. useCustomCompareEffect — Deep Compare, Your Rules

Sometimes the equality you want is neither shallow nor fully structural. Two cases come up often:

Compare by a single key (e.g., prev.id === next.id).
Compare with a library you already depend on (e.g., lodash.isEqual, dequal).

useCustomCompareEffect takes a third argument: a comparator that decides whether the new deps should trigger the effect.

import { useCustomCompareEffect } from "@reactuses/core";
import { dequal } from "dequal";

useCustomCompareEffect(
  () => loadDashboard(filters),
  [filters],
  (prev, next) => dequal(prev, next),
);

The benefit over useDeepCompareEffect is you control the cost. Deep equality on a 200-key config object is slow; (prev, next) => prev.version === next.version is one comparison. If you have a version field, use it.

This is also the right hook for fuzzy equality — e.g., "treat two scroll positions as equal if they are within 5 pixels of each other." The plain useEffect version requires a wrapper ref and a manual comparison inside the effect body; the custom-compare version puts the equality logic next to the deps.

7. useOnceEffect — Run Exactly Once, With Reactive Deps

useEffect(fn, []) runs once on mount, but the callback closes over whatever the deps would have been at that moment — usually undefined or initial values. If you actually want the first non-loading value of user to trigger an effect, neither useEffect(fn, [user]) (runs every time user changes) nor useEffect(fn, []) (runs at mount when user is still null) is correct.

useOnceEffect runs the effect the first time any dep changes from its initial value, then never again:

import { useOnceEffect } from "@reactuses/core";

function PersonalisedGreeting() {
  const { user } = useAuth(); // user is null until loaded

  useOnceEffect(() => {
    track("personalised_greeting_seen", { userId: user.id });
  }, [user]);

  return user ? <h1>Hi, {user.name}!</h1> : null;
}

The effect fires once — the first time user becomes non-null — and never fires again, even if user changes later. This is the right shape for first-paint analytics, one-time onboarding triggers, and "do this once the prerequisite is ready" patterns. The plain-React version of this is a ref-and-flag dance that everyone has written and nobody enjoys reading.

useOnceEffect also has a layout-effect sibling, useOnceLayoutEffect, for the same pattern when you need DOM measurements before paint.

8. useIsomorphicLayoutEffect — Stop the SSR Warnings

useLayoutEffect runs synchronously after DOM mutations and before paint. It is the right hook for reading layout (measuring an element's size) and writing to the DOM in the same tick (positioning a tooltip relative to a trigger). It is also the hook that prints this warning during server-side rendering:

useLayoutEffect does nothing on the server, because its effect cannot be encoded into the server renderer's output format.

The standard fix is to swap useLayoutEffect for useEffect when typeof window === "undefined". That is what useIsomorphicLayoutEffect does:

import { useIsomorphicLayoutEffect } from "@reactuses/core";

useIsomorphicLayoutEffect(() => {
  const { width } = ref.current!.getBoundingClientRect();
  setWidth(width);
}, []);

On the server, this is useEffect (which is a no-op during SSR — fine, because there is no layout to measure). On the client, it is useLayoutEffect (which fires synchronously, which is what you want for layout reads). One import, no warning, no special-casing.

This is the single most-copied snippet in the React ecosystem. If you have a useLayoutEffect anywhere in an SSR codebase (Next.js, Remix, Astro with islands), this hook should be the default.

9. useUpdateLayoutEffect — The Layout Variant of useUpdateEffect

The layout-effect sibling of useUpdateEffect. Same pattern: skip the first render, run on every subsequent dep change, but at layout-effect time so the DOM mutations happen before paint.

useUpdateLayoutEffect shines for layout-driven animations:

import { useUpdateLayoutEffect } from "@reactuses/core";

useUpdateLayoutEffect(() => {
  const el = listRef.current;
  if (!el) return;
  el.style.transform = `translateY(${activeIndex * itemHeight}px)`;
}, [activeIndex]);

Why not useUpdateEffect? Because useEffect fires after paint, and the slide animation will visibly start from the previous position before snapping to the new one. useLayoutEffect runs before paint, which means the new transform is applied in the same frame. Why not plain useLayoutEffect? Because on the first render activeIndex is the initial value and there is no animation to start.

The combination "layout effect that skips mount" is the right shape for "animate a change but not the initial value." It is also the right shape for managed focus: focus the new tab content when activeTab changes, but not when the component first mounts with activeTab="home".

When to Use Which: A Decision Table

The full set, in one place:

Situation	Hook
async/await effect body, want cancellation	`useAsyncEffect`
Skip the first run, react to subsequent changes	`useUpdateEffect`
Same as above but for layout effects	`useUpdateLayoutEffect`
Run a callback once on mount (intent is clearer)	`useMount`
Run a callback once on unmount (no stale capture)	`useUnmount`
Effect deps are objects, want structural equality	`useDeepCompareEffect`
Effect deps need a custom equality check	`useCustomCompareEffect`
Run once, but wait for a dep to become "ready"	`useOnceEffect`
Same as above for layout effects	`useOnceLayoutEffect`
Layout effect that doesn't warn during SSR	`useIsomorphicLayoutEffect`

Three rules to keep in mind:

Default to useEffect. Specialized hooks are for the cases above; do not reach for them speculatively.
Match layout to layout, async to async. If you are doing DOM measurement, the right family is the layout-effect hooks. If you are doing data fetching, the right family is useAsyncEffect. Mixing them produces flicker or race conditions.
useUpdateEffect is not "useEffect optimization." It changes behavior, not performance. The first render still happens, you just do not run the effect on it. If your goal is performance, look at the deps array, not at the hook.

A Realistic Combination

A common React pattern: a "search results" panel that fetches when the query changes, skips fetching on mount (the parent passed initial results), and announces "search updated" to screen readers — but not on mount, where the heading already conveys the same info.

import {
  useAsyncEffect,
  useUpdateEffect,
  useIsomorphicLayoutEffect,
} from "@reactuses/core";

function SearchResults({ query, initialResults }: {
  query: string;
  initialResults: Result[];
}) {
  const [results, setResults] = useState(initialResults);
  const announceRef = useRef<HTMLDivElement>(null);

  // Skip mount; fetch on every subsequent query change.
  useUpdateEffect(() => {
    let cancelled = false;
    fetch(`/api/search?q=${encodeURIComponent(query)}`)
      .then((r) => r.json())
      .then((data) => { if (!cancelled) setResults(data); });
    return () => { cancelled = true; };
  }, [query]);

  // Layout effect: read the results count and update aria-live before paint.
  // Skips mount because the initial heading already says it.
  useIsomorphicLayoutEffect(() => {
    if (!announceRef.current) return;
    announceRef.current.textContent = `${results.length} results for ${query}`;
  }, [results, query]);

  return (
    <>
      <div ref={announceRef} role="status" aria-live="polite" className="sr-only" />
      <ul>{results.map((r) => <li key={r.id}>{r.title}</li>)}</ul>
    </>
  );
}

Three behaviors, three hooks, no refs-and-flags. Replace the first useUpdateEffect with useAsyncEffect if the body grows complicated enough to want async/await; the rest stays the same.

Try Them Out

Every hook above has a runnable demo on its docs page. Read the demo, change the deps, watch what fires:

useEffect is a primitive. These hooks are the language you would build on top of it if you did it once and stopped re-inventing it across projects.

Timers in React Without setTimeout: useTimeout, useInterval, useCountDown, and useRafFn

reactuse.com — Mon, 18 May 2026 01:53:01 +0000

Timers in React Without setTimeout: useTimeout, useInterval, useCountDown, and useRafFn

Timers are one of those things every React developer writes by hand the first ten times and gets wrong on at least six of them. The pattern looks simple: call setTimeout in a useEffect, return a cleanup function, ship it. Then a code review finds the stale closure. Then a bug ticket arrives because the delay is being read from props at mount instead of from the current render. Then someone notices the interval keeps running after the component unmounts on a slow page. Then you discover that setInterval drifts a little every cycle and your countdown is off by 800ms after a minute. Then your performance audit flags the animation loop that nobody remembered to pause when the tab was hidden.

None of these bugs are interesting. They are all the same kind of bug: the timer logic is fine, the React integration is what breaks. ReactUse ships six small hooks that handle this integration once and let you write the timer logic by itself: useTimeout, useTimeoutFn, useInterval, useCountDown, useRafFn, and useRafState.

This post walks each one — what the underlying primitive is, what the manual version looks like in React, what bug the hook hides, and where it actually belongs in your code. By the end you should know which timer hook to reach for and why.

The Problem in One Snippet

Before any hooks, here is what almost every React codebase does at least once:

function Toast({ message, durationMs }: { message: string; durationMs: number }) {
  const [visible, setVisible] = useState(true);

  useEffect(() => {
    const id = setTimeout(() => setVisible(false), durationMs);
    return () => clearTimeout(id);
  }, [durationMs]);

  return visible ? <div className="toast">{message}</div> : null;
}

That is correct, mostly. The bug is what is missing:

The dependency array re-runs the effect every time durationMs changes — so a parent updating the prop mid-flight restarts the timer from zero instead of letting it finish.
There is no way to cancel the timer from outside (e.g., a "dismiss" button) without lifting the visible state up.
There is no way to read whether the timer is still pending — useful for tests, for analytics, for showing a "fading in 2s..." label.
The cleanup runs on unmount, which is good, but it also runs on every re-render that touches durationMs, which is usually not what you want.

You can fix all four with useRef plumbing, but it is the kind of plumbing nobody enjoys writing twice. That is exactly what useTimeoutFn exists for.

1. useTimeoutFn — The Correct setTimeout

useTimeoutFn(callback, interval, options?) schedules callback after interval ms and returns [isPending, cancel, restart]. Three concrete things it does that the naive version does not:

The latest callback is always called — no stale closures even if you do not list the callback in deps.
cancel() lets a parent or sibling component stop the timer without unmounting.
restart() lets you reset the clock without changing keys or remounting.

Rewriting Toast:

import { useTimeoutFn } from "@reactuses/core";

function Toast({ message, durationMs, onClose }: {
  message: string;
  durationMs: number;
  onClose: () => void;
}) {
  const [isPending, cancel, restart] = useTimeoutFn(onClose, durationMs);

  return (
    <div className="toast" onMouseEnter={cancel} onMouseLeave={() => restart()}>
      {message}
      {isPending && <span className="fade-bar" />}
    </div>
  );
}

Notice what disappeared: no useEffect, no setTimeout, no clearTimeout, no useRef, no useCallback. The hover behavior — pause the auto-dismiss while the user is reading the toast — is a one-liner. The isPending flag drives the fade bar without any extra state.

The immediate option (default true) controls whether the timer starts on mount. Set it to false for "fire on demand":

const [, , scheduleSave] = useTimeoutFn(saveDraft, 2000, { immediate: false });

return <textarea onChange={(e) => { setText(e.target.value); scheduleSave(); }} />;

Every keystroke pushes the save 2 seconds into the future. This is one way to build a "save 2 seconds after the user stops typing" debounce, though useDebounceFn is usually the cleaner choice for that specific pattern.

2. useTimeout — When You Just Want a Re-Render After N Milliseconds

useTimeout(ms, options?) is the same thing as useTimeoutFn but the callback is the component's own re-render. Useful when you want a piece of UI to "appear after a delay" without storing a boolean.

import { useTimeout } from "@reactuses/core";

function DelayedSpinner({ delayMs = 250 }: { delayMs?: number }) {
  const [isPending] = useTimeout(delayMs);
  return isPending ? null : <Spinner />;
}

The use case is "don't show a spinner for sub-250ms loads." If the parent finishes loading in 100ms, the spinner is never seen — no flash. If it takes longer, the spinner appears. No state, no effect, no boolean.

Same return shape as useTimeoutFn, so cancel and restart are there if you need to interrupt the re-render. In practice the read pattern dominates.

3. useInterval — The setInterval That Actually Pauses

useInterval(callback, delay, options?) runs callback every delay ms. The return value is { isActive, pause, resume }, not a tuple — useInterval is built around the pause/resume idea because that is the operation everyone needs and nobody implements correctly with raw setInterval.

The most common bug with setInterval in React is not the cleanup — modern linters catch that — it is passing null to stop the timer. With useInterval, that pattern just works:

import { useInterval } from "@reactuses/core";

function Polling({ active, onTick }: { active: boolean; onTick: () => void }) {
  useInterval(onTick, active ? 5000 : null);
  return null;
}

When active flips to false, the delay becomes null and the interval clears. When it flips back, the interval restarts at the new delay. No useEffect, no ref dance, no "did I clean up on the right value of active" worry.

If you prefer explicit pause/resume from outside the hook (for example, pausing polling while the user is offline), use the controls: true option and take the controls:

const { isActive, pause, resume } = useInterval(refresh, 5000, {
  controls: true,
  immediate: true,
});

useEffect(() => {
  const onVisibilityChange = () =>
    document.hidden ? pause() : resume();
  document.addEventListener("visibilitychange", onVisibilityChange);
  return () => document.removeEventListener("visibilitychange", onVisibilityChange);
}, [pause, resume]);

That snippet alone fixes a class of bugs that ships to production all the time: polling that continues at full rate while the user is on another tab, burning battery and rate-limited quota.

Why Not setInterval + Drift Correction?

setInterval does not guarantee an exact delay between calls — the browser may delay or batch callbacks when the page is throttled (background tab, low battery, Chrome's "intensive throttling"). For a polling loop this is fine. For a clock display it is visibly wrong: after 60 ticks of "every 1000ms" the displayed time can be a second or two behind the actual wall clock.

For clocks specifically, do not use useInterval to drive the display value. Use useInterval to schedule re-renders and read Date.now() inside the render:

function Clock() {
  const [, force] = useState(0);
  useInterval(() => force((n) => n + 1), 1000);
  return <span>{new Date().toLocaleTimeString()}</span>;
}

The interval is allowed to drift; the displayed time is read fresh on every render. Drift becomes a re-render scheduling concern, not a correctness concern.

4. useCountDown — Hours, Minutes, Seconds Without the Date Math

Countdowns are intervals with extra responsibility: track remaining time, format it for display, fire a callback when it hits zero, and stop the timer afterwards. The component-level version of this looks like 30 lines of code that everybody has written at least once.

useCountDown(time, format?, callback?) returns a [hours, minutes, seconds] tuple of strings (zero-padded) and handles all of the above:

import { useCountDown } from "@reactuses/core";

function OtpResend({ onExpire }: { onExpire: () => void }) {
  const [h, m, s] = useCountDown(60, undefined, onExpire);
  const expired = h === "00" && m === "00" && s === "00";

  return expired
    ? <button onClick={() => /* request again */ undefined}>Resend code</button>
    : <span>Resend in {m}:{s}</span>;
}

The hook owns the interval, the remaining-time state, and the callback dispatch. The component owns the rendering decision. If you want a different format (for example, Xm Ys or a raw seconds count), pass a format function that takes the remaining-seconds number and returns three strings — the hook calls it on every tick and returns whatever you give it.

useCountDown clamps to ["00", "00", "00"] once time runs out, and refuses to overflow past 99 hours, so you do not have to defend the view layer against silly inputs.

5. useRafFn — When You Need 60fps, Not "About Once Per Second"

setInterval(fn, 16) is the wrong way to run something on every frame. The browser already has a primitive for "do this once per frame, synchronized to the display refresh, and skip it if the tab is hidden" — requestAnimationFrame. useRafFn(callback, initiallyActive?) is the React wrapper around it.

The callback receives the current high-resolution timestamp (the same value requestAnimationFrame passes to its callback), and the hook returns [stop, start, isActive].

A canvas particle simulation, a smooth scroll position read, a CSS-variable-driven animation — anything that needs to update every frame should use useRafFn:

import { useRafFn } from "@reactuses/core";
import { useRef } from "react";

function FollowCursor() {
  const ref = useRef<HTMLDivElement>(null);
  const target = useRef({ x: 0, y: 0 });
  const current = useRef({ x: 0, y: 0 });

  useEffect(() => {
    const onMove = (e: MouseEvent) => { target.current = { x: e.clientX, y: e.clientY }; };
    window.addEventListener("mousemove", onMove);
    return () => window.removeEventListener("mousemove", onMove);
  }, []);

  useRafFn(() => {
    // Spring-ish lerp toward the target each frame
    current.current.x += (target.current.x - current.current.x) * 0.15;
    current.current.y += (target.current.y - current.current.y) * 0.15;
    if (ref.current) {
      ref.current.style.transform = `translate3d(${current.current.x}px, ${current.current.y}px, 0)`;
    }
  });

  return <div ref={ref} className="follower" />;
}

Two things to notice. First, the animation does not call setState. Pushing to ref.current.style keeps the work outside React's render cycle, which is the only way to get a real 60fps on a non-trivial page. Second, when the tab is hidden the browser stops firing requestAnimationFrame automatically — no useInterval-style throttling cliff, no manual pause logic needed for the common case.

If you do want manual control (for example, only animate while a panel is open), pass false as the second argument and call start()/stop() from your effect.

6. useRafState — Batched State Updates for Animations You Actually Re-render

useRafFn is great when you can mutate DOM directly. Sometimes you cannot — you have to push the new value into React state because it drives a JSX subtree. The naive version of this is:

const [pos, setPos] = useState({ x: 0, y: 0 });
// ... 60 setPos calls per second when the cursor moves

That works, but every setPos triggers a render. If the cursor fires mousemove faster than 60Hz (some browsers do), you get more renders than frames. useRafState solves this by batching state updates to requestAnimationFrame — at most one render per frame, even if setState is called many times in between.

import { useRafState } from "@reactuses/core";

function CursorBadge() {
  const [pos, setPos] = useRafState({ x: 0, y: 0 });

  useEventListener("mousemove", (e) => {
    setPos({ x: e.clientX, y: e.clientY });
  });

  return <div style={{ left: pos.x, top: pos.y }} className="badge" />;
}

The component re-renders at most 60 times per second regardless of how many mousemove events fire. It is a one-line drop-in replacement for useState whenever the source of updates is a high-frequency browser event (mouse, scroll, resize) and the target is JSX.

Pair this with useEventListener for the event side; pair with useRafFn instead when the target is a DOM mutation.

When to Use Which

The decision is not about preference — each hook fits a specific shape of problem:

You need to...	Reach for
Run a callback once after N ms	`useTimeoutFn`
Force a re-render once after N ms	`useTimeout`
Run a callback every N ms with pause/resume	`useInterval`
Display hh:mm:ss remaining	`useCountDown`
Do work every frame, no React state	`useRafFn`
Update React state on every frame at most	`useRafState`
Wait until the user stops typing	`useDebounceFn`
Cap callback rate to once per N ms	`useThrottleFn`

The last two — useDebounceFn and useThrottleFn — are not strictly timer hooks, but they live in the same family. The short version is "stop a high-frequency event from firing too often" rather than "schedule work in the future."

Three Mistakes the Hooks Quietly Prevent

A few subtle bugs the hooks above make impossible.

Mistake 1: The setTimeout in useState Initializer

const [id] = useState(() => setTimeout(callback, 1000)); // wrong

This schedules a timer that survives across React's intentional double-invocation in Strict Mode, and there is no cleanup. The "fix" with effects and refs is several lines. useTimeoutFn(callback, 1000) is one line and double-invocation safe by construction.

Mistake 2: Reading State Inside an Interval Callback

const [count, setCount] = useState(0);
useEffect(() => {
  const id = setInterval(() => setCount(count + 1), 1000);
  return () => clearInterval(id);
}, []); // captures count=0 forever — count goes 0, 1, 1, 1, 1...

This is the most-Googled React timer bug. The fix in plain React is either the functional updater (setCount((c) => c + 1)) or a ref. The fix with useInterval is "it already works" — the hook routes the latest callback through a ref internally.

Mistake 3: Animating React State at 60fps

const [x, setX] = useState(0);
useEffect(() => {
  const tick = () => { setX((v) => v + 1); requestAnimationFrame(tick); };
  requestAnimationFrame(tick);
}, []);

This works for one component. With ten on screen, React's render queue starts dropping frames because each setState triggers a full reconciliation. useRafFn lets you mutate DOM directly without going through React; useRafState caps re-renders to one per frame when DOM mutation is not an option. Either is correct; the loop above is correct only by accident.

Putting It Together: A "Tab Idle Refresher"

A small, realistic component to close on — a data card that polls every 30 seconds while the tab is visible and the user is active, and shows a countdown to the next refresh:

import { useInterval, useCountDown } from "@reactuses/core";
import { useState, useCallback } from "react";

function LiveStat({ fetchValue }: { fetchValue: () => Promise<number> }) {
  const [value, setValue] = useState<number | null>(null);
  const [error, setError] = useState<string | null>(null);
  const [, m, s] = useCountDown(30);

  const refresh = useCallback(async () => {
    try {
      setValue(await fetchValue());
      setError(null);
    } catch (e) {
      setError(e instanceof Error ? e.message : "Unknown error");
    }
  }, [fetchValue]);

  useInterval(refresh, 30_000, { immediate: true });

  return (
    <div className="card">
      <div className="value">{value ?? "—"}</div>
      <div className="footer">
        {error ? `Error: ${error}` : `Next refresh in ${m}:${s}`}
      </div>
    </div>
  );
}

useInterval owns the polling cadence. useCountDown owns the visual ticker. Neither is told about the other; both happen to land on the same number because they are seeded with the same constant. Two hooks, no useEffect, no setTimeout, no useRef.

Try Them Out

Every hook in this post has a runnable demo on its docs page. The fastest way to absorb the API surface is to read the demo, change one prop, and see what breaks:

Install with npm install @reactuses/core (or pnpm add @reactuses/core) and import directly. No provider, no setup, no peer dependencies beyond React 16.8+. The full hook list and source for everything we discussed is at reactuse.com.

Stop writing setTimeout in useEffect. The right hook for the job exists, and it is shorter.

React and User Preferences: Respect the OS Settings Your Users Already Picked

reactuse.com — Thu, 14 May 2026 02:04:06 +0000

React and User Preferences: Respect the OS Settings Your Users Already Picked

Every modern operating system asks the user, at some point, what kind of UI they want. Dark mode or light. High contrast or normal. Animations on or stripped down. Left-to-right or right-to-left. Preferred language. The user picks once, in System Settings, and from that moment on every well-built native app on the machine respects the choice. The web app you ship usually does not — it picks its own dark mode toggle, its own animation library, its own assumed-English copy, and the OS preference becomes a five-line note in someone's bug tracker.

The fix is small and the API surface is narrow. The browser exposes the OS preferences through window.matchMedia and navigator.language, and every modern React app can wire them up in an afternoon. The problem is not capability; it is that the wiring lives in the same useEffect/useState/SSR-mismatch swamp that every web feature lives in, and so it gets postponed forever. ReactUse ships seven focused hooks for this, and together they cover the four user-preference dimensions that actually matter: theme, motion, contrast, and locale.

This post walks through each one — what it returns, what bug it hides, and what shape the resulting component has. At the end we put them together into a single useAppearance() hook that reads the four signals at once.

1. usePreferredDark — The Boolean That Starts a Theme System

The simplest one. usePreferredDark() returns true if the user's OS is set to dark mode, false if not. It is a thin wrapper over window.matchMedia('(prefers-color-scheme: dark)').matches that handles two things you would otherwise have to handle yourself: SSR (no window) and live updates (the user can flip the OS toggle while your tab is open and it should react).

The Manual Way

import { useEffect, useState } from "react";

function ManualDark() {
  const [dark, setDark] = useState(false);

  useEffect(() => {
    const mq = window.matchMedia("(prefers-color-scheme: dark)");
    setDark(mq.matches);
    const onChange = (e: MediaQueryListEvent) => setDark(e.matches);
    mq.addEventListener("change", onChange);
    return () => mq.removeEventListener("change", onChange);
  }, []);

  return dark ? "dark" : "light";
}

That is correct, but the initial useState(false) is a guess — for SSR-rendered pages it produces a hydration mismatch the first time a dark-mode user lands on your site. The same fix applies in five places across a real codebase, and rarely with consistent defaults.

The ReactUse Way

import { usePreferredDark } from "@reactuses/core";

function Component() {
  const isDark = usePreferredDark();
  return <Theme name={isDark ? "dark" : "light"} />;
}

usePreferredDark is boolean in, boolean out — drop it anywhere in the tree, no setup. The first render returns the SSR-safe default; once the client mounts the real matchMedia value flows in and stays in sync as the user toggles.

2. usePreferredColorScheme — When "Dark" Is Not Enough

prefers-color-scheme has three values, not two: 'light', 'dark', and 'no-preference'. Most apps collapse the third into one of the first two, which is fine — until you ship a "follow system" mode and discover that some users explicitly set "no preference" and now your app picks the wrong default. usePreferredColorScheme returns the full string.

import { usePreferredColorScheme } from "@reactuses/core";

function ThemeBadge() {
  const scheme = usePreferredColorScheme();
  // scheme: "light" | "dark" | "no-preference"
  return <span>System theme: {scheme}</span>;
}

The most useful place for the three-value form is in a theme picker that has a "System" option:

type Choice = "light" | "dark" | "system";

function ThemePicker({ choice, onChange }: { choice: Choice; onChange: (c: Choice) => void }) {
  const scheme = usePreferredColorScheme();
  const effective =
    choice === "system"
      ? scheme === "dark"
        ? "dark"
        : "light"
      : choice;

  return (
    <fieldset>
      <legend>Theme</legend>
      {(["light", "dark", "system"] as const).map((c) => (
        <label key={c}>
          <input
            type="radio"
            checked={choice === c}
            onChange={() => onChange(c)}
          />
          {c}
          {c === "system" && ` (currently ${effective})`}
        </label>
      ))}
    </fieldset>
  );
}

The visible label tells the user what "System" actually means right now — a tiny touch that prevents the most common dark-mode confusion ("the system option is broken; it's giving me light").

3. useColorMode — Theme State With Persistence

usePreferredDark reports the OS preference. useColorMode goes a step further: it owns the application's applied theme. It reads the OS preference as a default, lets the user override it, persists the override to localStorage, and writes the chosen mode onto a class or attribute on <html> so your CSS can switch.

useColorMode is what you want for a real theme toggle:

import { useColorMode } from "@reactuses/core";

function ThemeToggle() {
  const [mode, setMode] = useColorMode();
  // mode: "light" | "dark" | "auto"

  return (
    <button onClick={() => setMode(mode === "dark" ? "light" : "dark")}>
      Switch to {mode === "dark" ? "light" : "dark"}
    </button>
  );
}

With one hook you get:

Initial value from localStorage if the user has set it before, otherwise from prefers-color-scheme
Live tracking of OS changes when in 'auto'
Class flipped on <html> (html.dark vs html.light) so your CSS works without any JS conditional
SSR-safe: the same mode is rendered on server and first client paint

A common gotcha when rolling your own theme system: the first paint shows the wrong mode for a heartbeat because the OS preference is read after hydration. useColorMode avoids this by writing the resolved mode synchronously during render and reading the persisted choice from localStorage before React picks up the tree. Pair it with a tiny inline <script> in your <head> to set the class even earlier and the flash is gone entirely.

4. useReducedMotion — The Cheapest Accessibility Win on the Web

prefers-reduced-motion is the OS-level signal that the user wants less movement on screen. People who get motion sick from parallax, vestibular-disorder users for whom large transitions are physically painful, anyone using a screen reader that already produces enough motion of its own — they all turn this on. Respecting it costs you nothing and earns enormous goodwill. Ignoring it is one of the fastest ways to ship an app that excludes users.

import { useReducedMotion } from "@reactuses/core";
import { motion } from "framer-motion";

function FadeIn({ children }: { children: React.ReactNode }) {
  const reduced = useReducedMotion();

  return (
    <motion.div
      initial={reduced ? { opacity: 1 } : { opacity: 0, y: 20 }}
      animate={{ opacity: 1, y: 0 }}
      transition={{ duration: reduced ? 0 : 0.4 }}
    >
      {children}
    </motion.div>
  );
}

When reduced motion is on, the component skips the y-translate and uses a 0ms transition — the content still appears, just without the animation. This is the right pattern: do not remove the visual change, remove the motion. A toast that fades in is still useful with no movement; a toast that does not appear at all is a bug.

useReducedMotion returns a boolean and is reactive to the OS setting, so a user who flips the preference mid-session sees animations stop immediately.

Common places to wire it up:

Page transitions
Modal/drawer enter-exit
Number-counting animations
Parallax / scroll-driven effects
Auto-playing carousels (also stop autoplay when reduced motion is on)

5. usePreferredContrast — Boost the Edges When Asked

prefers-contrast is a newer media feature that reports whether the user has asked their OS for higher or lower contrast. Values are 'more', 'less', 'no-preference', or 'custom'. Like reduced motion, it is a small group of users with a large benefit — high-contrast mode is critical for low-vision users.

import { usePreferredContrast } from "@reactuses/core";

function Card({ children }: { children: React.ReactNode }) {
  const contrast = usePreferredContrast();
  const cls =
    contrast === "more"
      ? "card card--high-contrast"
      : "card";
  return <div className={cls}>{children}</div>;
}

The high-contrast variant typically does three things: thicker borders, stronger color values (no pastel/muted backgrounds), and clearer focus rings. You do not need a parallel theme — just a few targeted overrides:

.card--high-contrast {
  border: 2px solid currentColor;
  background: var(--surface);
  color: var(--text-strong);
}
.card--high-contrast :focus-visible {
  outline: 3px solid var(--accent);
  outline-offset: 2px;
}

usePreferredContrast returns the raw string, so you can branch on 'more' vs 'less' independently if you have something useful to do for low-contrast users (most apps just match 'more' and ignore the rest).

6. usePreferredLanguages — Beyond `navigator.language`

The browser exposes navigator.languages — an ordered array of the user's preferred locales, e.g. ["en-US", "zh-CN", "ja-JP"]. Most apps read only navigator.language (the first entry), which throws away signal: a user with ["zh-CN", "en-US"] set wants Chinese first and English as a fallback, not whatever you guessed.

usePreferredLanguages returns the full array and stays in sync as the user changes browser language preferences:

import { usePreferredLanguages } from "@reactuses/core";

const SUPPORTED = ["en", "zh-Hans", "zh-Hant", "ja", "es"] as const;

function pickLocale(preferred: readonly string[]): string {
  for (const lang of preferred) {
    const base = lang.toLowerCase();
    if (SUPPORTED.includes(base as (typeof SUPPORTED)[number])) return base;
    const region = base.split("-")[0];
    const match = SUPPORTED.find((s) => s.toLowerCase().startsWith(region));
    if (match) return match;
  }
  return "en";
}

function LocaleAuto() {
  const preferred = usePreferredLanguages();
  const locale = pickLocale(preferred);
  return <App locale={locale} />;
}

The negotiation logic does what Accept-Language content negotiation has done on the server for decades: pick the highest-priority language the app supports, fall back gracefully, default to English at the end. The win over navigator.language is real: a user whose first preference is "de-CH" but second is "en" will land on your English version if you do not support German, instead of seeing a half-translated UI.

7. useTextDirection — RTL Is Not Just CSS

Right-to-left languages (Arabic, Hebrew, Persian) flip the entire reading direction of the page. CSS handles most of this through logical properties (margin-inline-start instead of margin-left), but a real RTL implementation also needs JavaScript-driven behavior to flip: keyboard arrow handling, scroll snapping in carousels, animation directions, drag-to-dismiss directions.

useTextDirection reads (and optionally writes) the dir attribute on a target element:

import { useEffect } from "react";
import { useTextDirection } from "@reactuses/core";

function App({ locale }: { locale: string }) {
  const [dir, setDir] = useTextDirection();

  useEffect(() => {
    setDir(isRtl(locale) ? "rtl" : "ltr");
  }, [locale, setDir]);

  return (
    <main>
      <Carousel direction={dir === "rtl" ? "leftward" : "rightward"} />
      <KeyboardHandler arrowsFlipped={dir === "rtl"} />
    </main>
  );
}

function isRtl(locale: string): boolean {
  return ["ar", "he", "fa", "ur"].some((p) => locale.startsWith(p));
}

By default the hook reads <html dir="...">, but it can target any element — useful for embedded widgets that need to be RTL-aware independently of the surrounding page.

Putting It All Together: useAppearance

Most apps want to read all four signals — color, motion, contrast, direction — in one place at the root, then thread them down through context. A single derived hook is cleaner than calling four hooks in every component:

import {
  usePreferredDark,
  usePreferredContrast,
  useReducedMotion,
  usePreferredLanguages,
  useTextDirection,
} from "@reactuses/core";

export type Appearance = {
  isDark: boolean;
  highContrast: boolean;
  reducedMotion: boolean;
  locale: string;
  dir: "ltr" | "rtl";
};

export function useAppearance(): Appearance {
  const isDark = usePreferredDark();
  const contrast = usePreferredContrast();
  const reducedMotion = useReducedMotion();
  const preferred = usePreferredLanguages();
  const [dir] = useTextDirection();

  const locale = pickLocale(preferred);

  return {
    isDark,
    highContrast: contrast === "more",
    reducedMotion,
    locale,
    dir: dir === "rtl" ? "rtl" : "ltr",
  };
}

Use it once at the root:

function App() {
  const appearance = useAppearance();

  return (
    <AppearanceContext.Provider value={appearance}>
      <html
        className={`${appearance.isDark ? "dark" : "light"} ${
          appearance.highContrast ? "contrast-more" : ""
        } ${appearance.reducedMotion ? "motion-reduce" : ""}`}
        dir={appearance.dir}
        lang={appearance.locale}
      >
        <Routes />
      </html>
    </AppearanceContext.Provider>
  );
}

The <html> element now reflects every preference the user has set: class for theme/contrast/motion variants, dir for direction, lang for locale. Every CSS rule that wants to branch on a preference can do so with a single attribute selector, and every component that needs the raw signal can pull it from AppearanceContext without re-subscribing to matchMedia.

CSS-First Where Possible, JS Where Necessary

A reasonable question: do you need JavaScript at all for half of this? prefers-color-scheme, prefers-reduced-motion, and prefers-contrast are all CSS media features and can be handled in stylesheets:

@media (prefers-reduced-motion: reduce) {
  * { animation-duration: 0.01ms !important; transition-duration: 0.01ms !important; }
}

For pure visual changes, CSS wins. The JavaScript hooks earn their keep when:

The preference drives behavior, not just appearance (carousel autoplay, animation duration values you pass to a library)
The preference toggles which component to mount (<Parallax /> vs <StaticImage />)
The preference influences a derived value that lives in React state (locale negotiation, theme persistence)
You want a user toggle that overrides the OS preference (useColorMode's 'auto' vs 'light' vs 'dark')

The rule of thumb: handle the static stuff in CSS, reach for these hooks when JavaScript actually needs to know.

Summary

Hook	Signal	Reach for it when…
`usePreferredDark`	OS dark mode preference	You need a boolean for theme picking
`usePreferredColorScheme`	Full `light`/`dark`/`no-preference`	You need the third value for "System" mode UX
`useColorMode`	Applied theme with persistence	You are building the theme system itself
`useReducedMotion`	`prefers-reduced-motion`	You pass duration to an animation lib, or gate motion-heavy components
`usePreferredContrast`	`prefers-contrast`	You ship a high-contrast variant
`usePreferredLanguages`	Full `navigator.languages`	You do locale negotiation, not just first-language detection
`useTextDirection`	`dir` attribute	You support RTL languages and need JS-driven flips

Respecting the OS preferences your users already picked is the cheapest accessibility upgrade you will ever ship. The bar is low — return a boolean, branch a className, pass a duration — and the win is high. Browse the rest of the catalog at reactuse.com, and if you flip prefers-reduced-motion on tomorrow and your app stops flinging cards across the screen, that is a good day.

React Observer Hooks: 7 Ways to Watch the DOM Without the Boilerplate

reactuse.com — Wed, 13 May 2026 11:09:03 +0000

React Observer Hooks: 7 Ways to Watch the DOM Without the Boilerplate

The DOM does not tell React when it changes. React owns one direction of the data flow — state goes in, markup comes out — and is mostly blind on the way back. If a third-party script injects a banner, if a font finishes loading and shoves the layout down 8 pixels, if a user resizes the window or scrolls a card into view, React has no idea unless you tell it. The browser ships four *Observer APIs to plug that gap, plus the getBoundingClientRect family for one-shot reads, and together they cover almost every "react to the DOM" requirement a real app has.

The trouble is that wiring observers into a React component is a small swamp of useEffect, useRef, cleanup functions, SSR guards, and the dreaded "observer fires before mount" race. Five lines of API turn into thirty lines of glue, and the glue is identical between components — so it gets copy-pasted, slightly mutated each time, and quietly accrues bugs. ReactUse ships seven focused hooks that hide the glue and give you back the API surface you actually wanted.

This post walks through all seven: what each observes, when to pick which, and what you would have written by hand if you had not picked them up.

1. useIntersectionObserver — "Is this element on screen?"

IntersectionObserver is the workhorse of modern lazy-loading. It reports when a target element crosses a threshold relative to the viewport (or a scroll container), without any of the scroll listener thrashing that the same job used to require. Lazy images, infinite scroll triggers, "viewed" tracking for analytics, fade-in on enter — all built on top of it.

The Manual Way

import { useEffect, useRef, useState } from "react";

function ManualOnScreen({ children }: { children: React.ReactNode }) {
  const ref = useRef<HTMLDivElement>(null);
  const [seen, setSeen] = useState(false);

  useEffect(() => {
    const el = ref.current;
    if (!el) return;
    const io = new IntersectionObserver(
      ([entry]) => {
        if (entry.isIntersecting) setSeen(true);
      },
      { rootMargin: "0px", threshold: 0.1 },
    );
    io.observe(el);
    return () => io.disconnect();
  }, []);

  return <div ref={ref}>{seen ? children : null}</div>;
}

This works, and the moment you need a second lazy section you copy it. By component number five you have five subtly different observers, three of them with the wrong threshold, one of them leaking because somebody refactored the cleanup. The shape is right; the repetition is not.

The ReactUse Way

useIntersectionObserver takes the ref and the options, and returns whether the element is currently intersecting:

import { useRef } from "react";
import { useIntersectionObserver } from "@reactuses/core";

function OnScreen({ children }: { children: React.ReactNode }) {
  const ref = useRef<HTMLDivElement>(null);
  const isVisible = useIntersectionObserver(ref, {
    threshold: 0.1,
  });

  return <div ref={ref}>{isVisible ? children : null}</div>;
}

The hook owns the observer's lifecycle: it disconnects on unmount, recreates the observer when the options change, and is SSR-safe. Lazy-load an image, fire an analytics event the first time a card enters the viewport, or defer mounting a heavy chart until it scrolls in — same hook, different boolean.

A common pattern is the "load more" trigger for infinite scroll: place a sentinel <div> at the bottom of a list and fire the fetch when it becomes visible. That is essentially the implementation of useInfiniteScroll, which builds on this primitive.

2. useElementVisibility — The Boolean You Usually Want

A surprising amount of the time you do not care about IntersectionObserverEntry at all — you just want a boolean, and you want it for the whole viewport, not a scroll container. useElementVisibility is exactly that.

import { useRef } from "react";
import { useElementVisibility } from "@reactuses/core";

function FadeInOnView({ children }: { children: React.ReactNode }) {
  const ref = useRef<HTMLDivElement>(null);
  const visible = useElementVisibility(ref);

  return (
    <div
      ref={ref}
      className={`fade ${visible ? "fade-in" : ""}`}
    >
      {children}
    </div>
  );
}

Use it for fade-in-on-scroll, "viewed" telemetry, and "pause this video when it scrolls off-screen" patterns. When you need finer control — a custom root, a threshold below 1, multiple thresholds — drop down to useIntersectionObserver.

3. useResizeObserver — The Right Way to Track Size

For about a decade, "track an element's size in React" meant attaching a window.resize listener and re-reading clientWidth on every event. That misses the most common case — the element resizing because its parent did, or because a sibling collapsed, or because a flex item below it grew. ResizeObserver fires on any size change to the observed element, regardless of cause.

The Manual Way

import { useEffect, useRef, useState } from "react";

function ManualSize() {
  const ref = useRef<HTMLDivElement>(null);
  const [size, setSize] = useState({ width: 0, height: 0 });

  useEffect(() => {
    const el = ref.current;
    if (!el) return;
    const ro = new ResizeObserver((entries) => {
      const cr = entries[0].contentRect;
      setSize({ width: cr.width, height: cr.height });
    });
    ro.observe(el);
    return () => ro.disconnect();
  }, []);

  return (
    <div ref={ref}>
      {size.width.toFixed(0)} × {size.height.toFixed(0)}
    </div>
  );
}

The hidden cost: every entry update calls setState, which schedules a render. Resize a parent quickly and the observed component re-renders 60 times a second. Most of the time you can live with this, but if the state is consumed by an expensive subtree you need to either throttle the updates or push them into a ref instead.

The ReactUse Way

useResizeObserver accepts the ref and a callback that fires on each entry:

import { useRef, useState } from "react";
import { useResizeObserver } from "@reactuses/core";

function ResponsiveCard() {
  const ref = useRef<HTMLDivElement>(null);
  const [variant, setVariant] = useState<"narrow" | "wide">("narrow");

  useResizeObserver(ref, ([entry]) => {
    setVariant(entry.contentRect.width > 600 ? "wide" : "narrow");
  });

  return <div ref={ref} data-variant={variant}>…</div>;
}

This is the container-query pattern in fifteen lines: the card swaps between a narrow and a wide layout based on its own width, not the viewport's. Place two of them in a flex row and they each pick their own layout independently.

4. useElementSize and useMeasure — Size in Two Flavors

If you only need width and height, the callback form is overkill. ReactUse ships two convenience hooks that wrap ResizeObserver and return state directly.

useElementSize returns { width, height } for the observed element:

import { useRef } from "react";
import { useElementSize } from "@reactuses/core";

function AutoFitGrid({ items }: { items: Item[] }) {
  const ref = useRef<HTMLDivElement>(null);
  const { width } = useElementSize(ref);
  const columns = Math.max(1, Math.floor(width / 240));

  return (
    <div
      ref={ref}
      style={{
        display: "grid",
        gridTemplateColumns: `repeat(${columns}, 1fr)`,
        gap: 16,
      }}
    >
      {items.map((it) => <Card key={it.id} item={it} />)}
    </div>
  );
}

The grid recomputes its column count whenever the container resizes — no media queries, no viewport guess, no JavaScript-controlled CSS variables.

useMeasure returns the full ResizeObserverEntry.contentRect (width, height, top, left, etc.) plus a ref to attach. Use it when you want size and the local coordinates in one call:

import { useMeasure } from "@reactuses/core";

function TooltipAnchor() {
  const [ref, rect] = useMeasure<HTMLButtonElement>();
  return (
    <>
      <button ref={ref}>Hover me</button>
      <Tooltip x={rect.left + rect.width / 2} y={rect.top} />
    </>
  );
}

The split between useElementSize and useMeasure is mostly ergonomic — pick whichever returns the shape your component already wants to consume.

5. useElementBounding — Position Plus Size, Synced

useElementBounding is the reactive equivalent of calling el.getBoundingClientRect() on every scroll and resize. It returns top, right, bottom, left, width, height, x, y — the full rect — and re-fires when the element moves or resizes for any reason.

import { useRef } from "react";
import { useElementBounding } from "@reactuses/core";

function StickyShadow() {
  const ref = useRef<HTMLDivElement>(null);
  const { top } = useElementBounding(ref);
  const stuck = top <= 0;

  return (
    <header
      ref={ref}
      className={stuck ? "header header--stuck" : "header"}
    >
      …
    </header>
  );
}

When a position: sticky header reaches the top of the viewport, its top becomes 0; the hook picks that up and the header gets a shadow. The same pattern works for floating action buttons that should change appearance once they leave their initial position, or popovers that need to track an anchor through layout changes.

The difference between useElementBounding and useMeasure: bounding is the viewport-relative rect (it changes on scroll), measure is the element's intrinsic content rect (it does not). Pick bounding when you care about position, measure when you care about size.

6. useMutationObserver — When the DOM Changes Around You

MutationObserver is the heaviest of the four observer APIs, and the one with the narrowest legitimate use case. It fires when attributes, child nodes, or text content change on a target. In a React-first app you almost never need it — React owns the mutations, so React knows them. You reach for useMutationObserver when something outside React is mutating the DOM:

A third-party widget (Stripe Elements, an embedded video player, a chat bubble) injects content into a slot.
A contentEditable element is being edited by the user, and you want to react to text changes without polling.
A scripts toggles aria-expanded or data-state on an element you do not control, and you want to mirror it into React state.

import { useRef, useState } from "react";
import { useMutationObserver } from "@reactuses/core";

function ThirdPartyMount({ slot }: { slot: string }) {
  const ref = useRef<HTMLDivElement>(null);
  const [ready, setReady] = useState(false);

  useMutationObserver(
    ref,
    (mutations) => {
      const injected = mutations.some(
        (m) => m.type === "childList" && m.addedNodes.length > 0,
      );
      if (injected) setReady(true);
    },
    { childList: true, subtree: true },
  );

  return (
    <div ref={ref} data-third-party={slot}>
      {!ready && <Skeleton />}
    </div>
  );
}

The skeleton renders until the third-party script drops its content into the slot, then disappears. Without MutationObserver, your options were setInterval polling or MutationObserver plus a hand-rolled lifecycle — the former is wasteful, the latter is exactly what this hook saves you from.

A common pitfall: MutationObserver is fast but not free, and an unscoped subtree watcher on a busy element can fire dozens of times per second. Always pass the narrowest options object you can — if you only care about childList, do not pass attributes: true.

7. Choosing Between Them

The seven hooks overlap, and the overlap is intentional — different shapes work for different consumers. The cheat sheet:

You want…	Hook
A boolean for "is this on screen?"	`useElementVisibility`
Visibility with a custom root or threshold	`useIntersectionObserver`
Width and height as state	`useElementSize`
The full content rect as state	`useMeasure`
The viewport-relative rect (changes on scroll)	`useElementBounding`
A callback on every resize entry	`useResizeObserver`
To react to DOM changes from outside React	`useMutationObserver`

A useful mental model: visibility hooks tell you where an element is relative to the user; size and bounding hooks tell you how big it is and where in the layout; mutation tells you what changed inside it.

A Worked Example: A Self-Sizing Lazy Card

Putting four of them together — a card that lazy-mounts its expensive chart only after it scrolls in, picks a layout based on its own width, and positions a tooltip relative to itself:

import { useRef, useState } from "react";
import {
  useElementVisibility,
  useElementSize,
  useElementBounding,
} from "@reactuses/core";

function LazyChartCard({ data }: { data: ChartData }) {
  const cardRef = useRef<HTMLDivElement>(null);
  const visible = useElementVisibility(cardRef);
  const { width } = useElementSize(cardRef);
  const { top, left } = useElementBounding(cardRef);

  const [hovered, setHovered] = useState(false);
  const layout = width > 600 ? "horizontal" : "vertical";

  return (
    <>
      <div
        ref={cardRef}
        data-layout={layout}
        className="card"
        onMouseEnter={() => setHovered(true)}
        onMouseLeave={() => setHovered(false)}
      >
        {visible ? <Chart data={data} /> : <Skeleton />}
      </div>
      {hovered && (
        <Tooltip
          x={left + width / 2}
          y={top - 8}
          text={`${data.label}: ${data.value}`}
        />
      )}
    </>
  );
}

The chart only constructs once it enters the viewport. The card flips its layout based on its own width, not the page's. The tooltip floats above the card by tracking its bounding rect, so it stays anchored through scrolls and layout shifts. Three hooks, twenty lines of glue, zero useEffect blocks, zero addEventListener/removeEventListener pairs.

Performance Notes

Observers are not free, but the cost is concentrated and well-understood:

One observer per element is fine; one per row of a thousand-row list is not. For list virtualization, observe the scroll container once and resolve which row is visible inside the callback. The browser will sometimes coalesce many IntersectionObserver targets, but a long list with per-row observers still hurts.
useResizeObserver callbacks run on a separate task. Reading layout (getBoundingClientRect, offsetWidth) inside the callback is cheap; writing layout is also fine, with the catch that the write can trigger another resize entry. Guard against feedback loops by debouncing or by writing into a requestAnimationFrame.
MutationObserver is the most expensive of the four, especially with subtree: true. Scope it as narrowly as possible. If you find yourself watching a large subtree, consider whether a single explicit "third-party-ready" event from the embedded code would be cheaper.

Summary

The observer APIs are the bridge between "what React knows" and "what the DOM actually does." Wired with raw useEffect they accumulate a lot of glue and a long tail of subtle bugs. Wired with these seven hooks they become one-liners that compose freely.

Use useIntersectionObserver and useElementVisibility for "is this on screen."
Use useResizeObserver, useElementSize, and useMeasure for "how big is this."
Use useElementBounding for "where is this in the viewport."
Use useMutationObserver for "what did the DOM do behind my back."

Browse the rest at reactuse.com — and if you replace a chunky useEffect-plus-observer dance with one of these, that is a good day at the keyboard.

Browser Tab UX in React: Pull Users Back with Titles, Favicons, and Notifications

reactuse.com — Sat, 09 May 2026 02:18:21 +0000

Browser Tab UX in React: Pull Users Back with Titles, Favicons, and Notifications

The average laptop has thirty open tabs at any moment, and your app is one of them. The user opens it, switches away to read Slack, comes back fifteen minutes later, and forgets which tab was yours. If your tab title is still "My App" and the favicon is still the same gray square it has been since launch, you have wasted that fifteen minutes — there was a new message, a build finished, an upload completed, and the user never knew.

The browser already gives you a small but powerful surface for getting attention back: the tab title, the favicon, the visibility state, the focus event, and the system notification. Wired up correctly, an inactive tab can announce "(3) New messages — Acme Chat", flash a red badge on the favicon, pause its expensive polling while hidden, refresh the moment it comes back, and fire a native OS notification when something urgent happens. Wired up incorrectly, the same code leaks event listeners, fights with React's render cycle, and ships a hydration mismatch on the first SSR pass.

This post walks through six primitives for building attention-aware UI in React, using focused hooks from ReactUse. For each one we will look at the manual implementation, the gotchas, and then the hook that hides them. At the end we combine all six into a chat-tab component that behaves like a real native app.

1. The Tab Title as a Notification Channel

The <title> element is the most underused notification surface on the web. Gmail, GitHub, Linear, and Discord all use it: a leading (N) count or a • dot tells you something happened without you switching tabs. The implementation is one line — document.title = "..." — but doing it inside a React component the wrong way leaves the title stuck on whatever the last render set, even after the component unmounts.

The Manual Way

import { useEffect, useState } from "react";

function ManualUnreadTitle({ count }: { count: number }) {
  useEffect(() => {
    const previous = document.title;
    document.title = count > 0 ? `(${count}) Acme Chat` : "Acme Chat";
    return () => {
      document.title = previous;
    };
  }, [count]);

  return null;
}

The visible bug is subtle: previous captures whatever the title was at the moment this effect ran, which means if a parent component sets the title between renders, the cleanup function restores a stale value. The fix is to either pick a single source of truth for the title or to skip the cleanup entirely and let the next render overwrite. Most apps end up with the latter, then forget to write the cleanup at all, then ship a stuck-title bug six months later when somebody adds React StrictMode and the effect fires twice.

The ReactUse Way: useTitle

useTitle takes a single string and reflects it onto document.title whenever the string changes:

import { useTitle } from "@reactuses/core";

function UnreadTitle({ count }: { count: number }) {
  useTitle(count > 0 ? `(${count}) Acme Chat` : "Acme Chat");
  return null;
}

That is the entire component. The hook subscribes to its own input, not to the previous DOM value, so no stale-cleanup bug is possible. Drop it anywhere in the tree — typically at the page root or inside the component that owns the unread count — and the tab updates as the data changes.

A common pattern is to combine it with a derived count from a chat store:

import { useTitle } from "@reactuses/core";
import { useChatStore } from "./store";

function ChatTitle() {
  const unread = useChatStore((s) => s.unreadCount);
  const channel = useChatStore((s) => s.activeChannel?.name ?? "Chat");
  useTitle(unread > 0 ? `(${unread}) ${channel} — Acme` : `${channel} — Acme`);
  return null;
}

The component renders nothing visually. It exists to keep the title in sync with the store. Mount it once at the top of your app and forget it.

2. State-Aware Favicons

The favicon has even less screen real estate than the title — sixteen pixels square — but it is the one thing the user sees in the tab bar when titles get truncated. Swapping it on state changes (idle gray, attention red, error orange, success green) is one of the cheapest UX wins in the browser.

The Manual Way

import { useEffect } from "react";

function ManualFavicon({ status }: { status: "idle" | "alert" | "error" }) {
  useEffect(() => {
    const link = document.querySelector<HTMLLinkElement>("link[rel='icon']");
    if (!link) return;
    link.href =
      status === "idle"
        ? "/favicon.ico"
        : status === "alert"
        ? "/favicon-alert.ico"
        : "/favicon-error.ico";
  }, [status]);

  return null;
}

This works in the happy path and breaks in three: when there is no <link rel="icon"> element to start with (some bundlers strip it), when there are multiple icon links of different sizes (Apple touch icons, manifest icons), and when SSR renders a different icon than the client wants. You end up with branching logic for each case.

The ReactUse Way: useFavicon

useFavicon handles all three cases. It updates every link[rel*="icon"] tag it finds, creates one if none exist, and supports a base URL prefix for assets served from a CDN.

import { useFavicon } from "@reactuses/core";

function StatusFavicon({ status }: { status: "idle" | "alert" | "error" }) {
  const href =
    status === "idle"
      ? "/favicon.ico"
      : status === "alert"
      ? "/favicon-alert.ico"
      : "/favicon-error.ico";
  useFavicon(href);
  return null;
}

A neat trick is to combine it with the unread count for a "badged" favicon. Pre-render a few PNG variants (favicon-1.png through favicon-9.png, plus favicon-9plus.png) and pick one based on the count:

import { useFavicon } from "@reactuses/core";

function BadgedFavicon({ count }: { count: number }) {
  const variant =
    count === 0 ? "" : count > 9 ? "-9plus" : `-${count}`;
  useFavicon(`/favicon${variant}.png`);
  return null;
}

Now the tab bar shows a numbered favicon as messages pile up, even when the title is truncated past the count.

3. Pause Expensive Work When the Tab is Hidden

Every app has at least one polling interval, animation, or video that should stop when nobody is looking. Browsers throttle background tabs, but throttling is not the same as stopping — a 1-second poll that becomes a 60-second poll still hits the server, still parses JSON, still updates state, still triggers a render that nobody sees. The Page Visibility API lets you pause cleanly.

The Manual Way

import { useEffect, useState } from "react";

function ManualVisibility() {
  const [hidden, setHidden] = useState(document.hidden);

  useEffect(() => {
    const onChange = () => setHidden(document.hidden);
    document.addEventListener("visibilitychange", onChange);
    return () => document.removeEventListener("visibilitychange", onChange);
  }, []);

  return hidden ? "hidden" : "visible";
}

Two problems. First, on the server document is undefined, so the initial state crashes SSR. Second, the visibilitychange event does not fire on the first paint — if the user navigates to your page while it is already in a background tab, your initial document.hidden is correct but you never re-read it on focus.

The ReactUse Way: useDocumentVisibility

useDocumentVisibility handles SSR via a defaultValue argument and re-syncs after mount.

import { useEffect } from "react";
import { useDocumentVisibility } from "@reactuses/core";

function PriceTicker() {
  const visibility = useDocumentVisibility("visible");
  const [price, setPrice] = useState<number | null>(null);

  useEffect(() => {
    if (visibility === "hidden") return;
    const id = setInterval(async () => {
      const r = await fetch("/api/price");
      setPrice((await r.json()).price);
    }, 1000);
    return () => clearInterval(id);
  }, [visibility]);

  return <span>${price ?? "—"}</span>;
}

The interval mounts when the tab is visible, unmounts when it hides, and remounts when it comes back. No throttled-but-still-running poll, no wasted bandwidth, and the user sees a fresh price the moment they switch back.

The hook returns the actual DocumentVisibilityState ('visible' | 'hidden') rather than a boolean, which matches the spec and makes future visibility states (the spec leaves room for 'prerender') drop in cleanly.

4. Refresh on Focus

visibilitychange fires when the tab becomes visible, but a tab can be visible without being focused — picture-in-picture, side-by-side windows, or a tab that is the foreground tab in a background window. For "the user just clicked back to me" semantics you want window focus, not just visibility.

The Manual Way

import { useEffect, useState } from "react";

function ManualFocus() {
  const [focused, setFocused] = useState(false);

  useEffect(() => {
    setFocused(document.hasFocus());
    const onFocus = () => setFocused(true);
    const onBlur = () => setFocused(false);
    window.addEventListener("focus", onFocus);
    window.addEventListener("blur", onBlur);
    return () => {
      window.removeEventListener("focus", onFocus);
      window.removeEventListener("blur", onBlur);
    };
  }, []);

  return focused ? "focused" : "blurred";
}

Same story as before — three event listeners, an initial-state read, an SSR pitfall.

The ReactUse Way: useWindowsFocus

useWindowFocus (exported as useWindowsFocus — the legacy name is preserved) returns a boolean and re-syncs on mount.

import { useEffect } from "react";
import { useWindowsFocus } from "@reactuses/core";

function FreshFeed() {
  const focused = useWindowsFocus();
  const [items, setItems] = useState<Item[]>([]);

  useEffect(() => {
    if (!focused) return;
    fetch("/api/feed").then((r) => r.json()).then(setItems);
  }, [focused]);

  return <Feed items={items} />;
}

The feed re-fetches every time the user clicks back to the window. Combined with useDocumentVisibility, you can pause a poll when hidden and refresh once when refocused — covering both the "long absence" and "quick glance" cases.

5. Catch the User Before They Leave

usePageLeave reports when the mouse moves out of the viewport — usually toward the tab bar or the address bar, often a leading indicator that the user is about to switch tabs. It is the foundation of "exit intent" overlays, which are a divisive pattern when used for ad popups but a useful one when used for "you have unsaved changes" hints or "before you go, here is what you missed" prompts.

import { usePageLeave } from "@reactuses/core";

function UnsavedHint({ dirty }: { dirty: boolean }) {
  const isLeaving = usePageLeave();
  if (!dirty || !isLeaving) return null;
  return (
    <div className="toast">
      You have unsaved changes. Press ⌘S to save.
    </div>
  );
}

The hook listens for mouseout, mouseleave, and mouseenter and flips its boolean as the cursor crosses the viewport edge. Use it sparingly — every site that has shoved a "wait, before you go!" modal in your face on the way out is a reminder that this pattern goes from helpful to annoying very quickly.

A more restrained version: combine it with a dirty-form flag, so the hint only fires when there is actually something at stake.

6. Native Notifications — Permission First

The Notification API is the only one of these surfaces that escapes the browser entirely. A native OS notification fires even if your tab is fully buried, even if the window is minimized, even if the user is in another app. It is also the only one that requires explicit user permission, and getting the prompt UX wrong is the fastest way to a permanent "deny" in browser settings.

The two hooks that pair here are usePermission and useWebNotification.

Check the State Before You Ask

usePermission wraps the Permissions API and returns the current state for any permission name — 'granted', 'denied', 'prompt', or empty if the API is not supported. Use it to decide whether to render an "Enable notifications" button (state is 'prompt'), a "You're all set" indicator ('granted'), or a "Notifications are blocked — fix in browser settings" link ('denied').

import { usePermission } from "@reactuses/core";

function NotificationStatus() {
  const state = usePermission("notifications");
  if (state === "granted") return <span>Notifications: on</span>;
  if (state === "denied") return <a href="#help">Notifications blocked — fix</a>;
  return null;
}

Ask Only on User Intent

useWebNotification returns isSupported, show, close, and ensurePermissions. The cardinal rule of the Notification API: never call Notification.requestPermission() on page load. Browsers display the permission prompt as a tab-level chrome popup, and a popup that fires before the user has interacted with your page is the textbook "deny by reflex" UX.

Trigger the request from a button click instead:

import { useWebNotification } from "@reactuses/core";

function EnableButton() {
  const { isSupported, ensurePermissions, show } = useWebNotification();
  if (!isSupported) return null;

  return (
    <button
      onClick={async () => {
        const granted = await ensurePermissions();
        if (granted) {
          show("You're all set", {
            body: "We'll let you know about new messages here.",
            icon: "/favicon.ico",
          });
        }
      }}
    >
      Enable desktop notifications
    </button>
  );
}

Once the user has granted permission, calling show(title, options) from anywhere in your app fires a native notification. The hook tears down its current notification on unmount, so a notification fired from a component that immediately unmounts will not stick around forever.

Putting it All Together: An Attention-Aware Chat Tab

Here is what a chat tab looks like with all six primitives wired in. Unread messages update the title and the favicon; polling pauses while hidden and refreshes on focus; an exit-intent hint fires for unsaved drafts; and a native notification fires when a new message arrives while the tab is in the background.

import { useEffect, useRef } from "react";
import {
  useTitle,
  useFavicon,
  useDocumentVisibility,
  useWindowsFocus,
  usePageLeave,
  useWebNotification,
} from "@reactuses/core";
import { useChatStore } from "./store";

export function AttentionAwareChat() {
  const unread = useChatStore((s) => s.unreadCount);
  const channel = useChatStore((s) => s.activeChannel?.name ?? "Chat");
  const draftDirty = useChatStore((s) => s.composer.length > 0);
  const latest = useChatStore((s) => s.latestMessage);
  const fetchFeed = useChatStore((s) => s.fetchFeed);

  // 1 + 2: title + favicon reflect unread count
  useTitle(unread > 0 ? `(${unread}) ${channel} — Acme` : `${channel} — Acme`);
  const variant = unread === 0 ? "" : unread > 9 ? "-9plus" : `-${unread}`;
  useFavicon(`/favicon${variant}.png`);

  // 3: pause polling when hidden
  const visibility = useDocumentVisibility("visible");
  useEffect(() => {
    if (visibility === "hidden") return;
    const id = setInterval(fetchFeed, 5000);
    return () => clearInterval(id);
  }, [visibility, fetchFeed]);

  // 4: full refresh on focus
  const focused = useWindowsFocus();
  useEffect(() => {
    if (focused) fetchFeed();
  }, [focused, fetchFeed]);

  // 5: exit-intent hint when there is an unsaved draft
  const isLeaving = usePageLeave();

  // 6: native notification when a new message arrives in the background
  const { show, ensurePermissions, isSupported } = useWebNotification();
  const lastNotifiedId = useRef<string | null>(null);
  useEffect(() => {
    if (!isSupported || !latest || visibility === "visible") return;
    if (lastNotifiedId.current === latest.id) return;
    lastNotifiedId.current = latest.id;
    show(`${latest.author} in ${channel}`, {
      body: latest.text,
      icon: "/favicon.ico",
      tag: "chat-message",
    });
  }, [latest, visibility, channel, show, isSupported]);

  return (
    <>
      <ChatPane />
      {draftDirty && isLeaving && (
        <Toast>You have an unsaved draft.</Toast>
      )}
      {!isSupported || (
        <button onClick={ensurePermissions}>Enable desktop notifications</button>
      )}
    </>
  );
}

Six hooks, one component, no manual event listeners, no SSR crashes, no leaked timers. Every line of attention-management logic is colocated with the chat that owns it, so the next person reading the file knows where to look.

Summary

Hook	What it is for	When to reach for it
`useTitle`	Reflect a string into `document.title`	Unread counts, build status, document name
`useFavicon`	Swap the favicon `href` reactively	Status badges, attention dots, branded states
`useDocumentVisibility`	Track tab hidden vs visible	Pause polls, animations, video
`useWindowFocus`	Track window focus	Refresh on return, pause on blur
`usePageLeave`	Detect cursor leaving viewport	Exit-intent hints, unsaved-draft warnings
`usePermission`	Read Permissions API state	Conditional CTAs for notifications, geo, etc.
`useWebNotification`	Show native OS notifications	Background message alerts, build-done pings

Browser-tab UX is one of those areas where the gap between "good app" and "great app" is small in code and large in feel. Six hooks, twenty lines of glue, and your app starts to behave like the native ones it competes with for attention. Browse the rest of the catalog at reactuse.com — and if you ship one of these tomorrow, drop us a screenshot.

React Form Handling: Debounced Validation, Auto-Save Drafts, and Controlled Inputs

reactuse.com — Fri, 08 May 2026 02:44:44 +0000

React Form Handling: Debounced Validation, Auto-Save Drafts, and Controlled Inputs

Forms are the most rewritten part of every React app. They look easy on day one — slap a <input>, wire onChange to useState, ship it. By month three, the same form has grown async username validation, an auto-saved draft, a custom date popover, and a controlled-or-uncontrolled toggle that has to play nicely with the design system. Each of those features pulls in its own ad-hoc state machine, its own effect cleanup, and its own pile of edge cases. The form file becomes the longest in the codebase, and nobody on the team wants to touch it.

This post walks through four primitives that every non-trivial form needs eventually: a debounced value to throttle async validation, a controlled-or-uncontrolled wrapper that lets a component accept either pattern, a localStorage-backed draft that survives refreshes, and a click-outside detector that closes popovers without leaking listeners. For each one we will build the manual version first so the trade-offs are visible, then swap it for a focused hook from ReactUse. At the end, we combine all four into a single account-settings form that validates as you type, auto-saves drafts, and handles a country-picker popover.

1. Debounced Async Validation

The Manual Way

The classic mistake in async validation is firing a request on every keystroke. The classic fix is setTimeout, and the classic bug is forgetting to clear the previous timer:

import { useEffect, useState } from "react";

function ManualUsernameField() {
  const [username, setUsername] = useState("");
  const [debounced, setDebounced] = useState("");
  const [status, setStatus] = useState<"idle" | "checking" | "ok" | "taken">("idle");

  useEffect(() => {
    const id = setTimeout(() => setDebounced(username), 400);
    return () => clearTimeout(id);
  }, [username]);

  useEffect(() => {
    if (!debounced) {
      setStatus("idle");
      return;
    }
    let cancelled = false;
    setStatus("checking");
    fetch(`/api/username?u=${encodeURIComponent(debounced)}`)
      .then((r) => r.json())
      .then((data) => {
        if (!cancelled) setStatus(data.available ? "ok" : "taken");
      });
    return () => {
      cancelled = true;
    };
  }, [debounced]);

  return (
    <label>
      Username
      <input value={username} onChange={(e) => setUsername(e.target.value)} />
      <span>{status}</span>
    </label>
  );
}

There are two effects here doing two different jobs, and they have to stay in sync. The first one is a debouncer: turn rapid username changes into a single delayed debounced value. The second one is a request runner: when debounced changes, fire a request and ignore the result if a newer one comes back. Both effects need their own cleanup. If you forget the clearTimeout you double up requests; if you forget the cancelled flag you race and the older response can overwrite the newer one.

The real cost is not lines of code — it is that the debounce logic is welded to this particular field. Reuse it on the email field and you copy-paste the same five lines.

The ReactUse Way: useDebounce

useDebounce returns a value that lags behind its input by a fixed delay:

import { useEffect, useState } from "react";
import { useDebounce } from "@reactuses/core";

function UsernameField() {
  const [username, setUsername] = useState("");
  const debounced = useDebounce(username, 400);
  const [status, setStatus] = useState<"idle" | "checking" | "ok" | "taken">("idle");

  useEffect(() => {
    if (!debounced) {
      setStatus("idle");
      return;
    }
    let cancelled = false;
    setStatus("checking");
    fetch(`/api/username?u=${encodeURIComponent(debounced)}`)
      .then((r) => r.json())
      .then((data) => {
        if (!cancelled) setStatus(data.available ? "ok" : "taken");
      });
    return () => {
      cancelled = true;
    };
  }, [debounced]);

  return (
    <label>
      Username
      <input value={username} onChange={(e) => setUsername(e.target.value)} />
      <span>{status}</span>
    </label>
  );
}

The first effect — the debouncing one — is gone. useDebounce owns the timer and its cleanup. What remains is the part that is genuinely about your form: when the debounced value changes, run a validation request and discard stale responses.

The hook also pairs naturally with the equivalent function-debouncer, useDebounceFn, when you want to debounce an event handler instead of a value — useful for "save on blur" and similar patterns where the trigger is a callback rather than a state change.

2. Controlled or Uncontrolled — Pick One, Support Both

The Manual Way

Library components have a recurring dilemma: should the consumer pass value and onChange, or should the component manage its own state with a defaultValue? The honest answer is "both, depending on who's calling." Most teams reinvent this pattern field by field:

function ManualToggle({
  value,
  defaultValue = false,
  onChange,
}: {
  value?: boolean;
  defaultValue?: boolean;
  onChange?: (next: boolean) => void;
}) {
  const isControlled = value !== undefined;
  const [internal, setInternal] = useState(defaultValue);
  const current = isControlled ? value : internal;

  const handleClick = () => {
    const next = !current;
    if (!isControlled) setInternal(next);
    onChange?.(next);
  };

  return (
    <button role="switch" aria-checked={current} onClick={handleClick}>
      {current ? "On" : "Off"}
    </button>
  );
}

The pattern is simple in isolation but a magnet for subtle bugs. What if the consumer flips between controlled and uncontrolled by passing undefined mid-render? What if they pass value but no onChange? React's own form inputs warn about both of these, but custom components rarely bother — and as your design system grows, the boilerplate is duplicated across every input, switch, slider, and date picker.

The ReactUse Way: useControlled

useControlled collapses the whole pattern into a single hook call:

import { useControlled } from "@reactuses/core";

function Toggle({
  value,
  defaultValue = false,
  onChange,
}: {
  value?: boolean;
  defaultValue?: boolean;
  onChange?: (next: boolean) => void;
}) {
  const [current, setCurrent] = useControlled({
    value,
    defaultValue,
    onChange,
  });

  return (
    <button
      role="switch"
      aria-checked={current}
      onClick={() => setCurrent(!current)}
    >
      {current ? "On" : "Off"}
    </button>
  );
}

The hook does three things you would otherwise write yourself:

Decides controlled vs uncontrolled once, on the first render, and warns if the mode flips later — same diagnostic React's built-in inputs use.
Returns a stable setter that internally branches on the mode: in uncontrolled mode it updates internal state; in controlled mode it just calls onChange and lets the parent re-render.
Always reflects the latest source of truth. The first tuple element is value when controlled and the internal state when not, so consumers never see a mismatch.

You can drop this into any input-shaped component in your design system and stop thinking about the pattern.

3. Auto-Saving Form Drafts

The Manual Way

Long forms — onboarding flows, settings pages, content editors — should never lose a user's work to a refresh. The standard fix is to mirror the form state into localStorage, and the standard mistake is to do it on every keystroke:

function ManualDraftForm() {
  const [draft, setDraft] = useState(() => {
    if (typeof window === "undefined") return { title: "", body: "" };
    const raw = localStorage.getItem("post-draft");
    return raw ? JSON.parse(raw) : { title: "", body: "" };
  });

  useEffect(() => {
    localStorage.setItem("post-draft", JSON.stringify(draft));
  }, [draft]);

  return (
    <form>
      <input
        value={draft.title}
        onChange={(e) => setDraft((d) => ({ ...d, title: e.target.value }))}
      />
      <textarea
        value={draft.body}
        onChange={(e) => setDraft((d) => ({ ...d, body: e.target.value }))}
      />
    </form>
  );
}

Three problems hide in those fifteen lines. First, the lazy initializer reads localStorage on every mount but does not re-read if another tab updated it — multi-tab editing breaks silently. Second, the JSON.parse will throw on corrupted data and crash the component on mount. Third, localStorage.setItem is synchronous and runs on every render, which on a fast-typing user can pin the main thread.

The SSR check at the top is the giveaway that this is a recipe other components in your codebase will copy and probably get wrong.

The ReactUse Way: useLocalStorage

useLocalStorage looks like useState and behaves like useState, but the value lives in storage:

import { useLocalStorage } from "@reactuses/core";

function DraftForm() {
  const [draft, setDraft] = useLocalStorage("post-draft", {
    title: "",
    body: "",
  });

  return (
    <form>
      <input
        value={draft.title}
        onChange={(e) => setDraft({ ...draft, title: e.target.value })}
      />
      <textarea
        value={draft.body}
        onChange={(e) => setDraft({ ...draft, body: e.target.value })}
      />
    </form>
  );
}

The hook handles the four things the manual version got wrong or skipped:

SSR-safe initialization. On the server it returns the default; the stored value hydrates on the first client render without a mismatch.
Cross-tab sync. Listens to storage events and updates state when another tab writes to the same key.
JSON-safe. Catches parse errors and falls back to the default rather than crashing.
Stable setter. The returned setter has a stable identity, so you can pass it to useEffect deps or memoized children without churn.

For really long forms you often want auto-save plus debounce. Combine with useDebounce from section 1 — debounce the form state, then write the debounced value to storage — and you get an editor that survives refreshes without thrashing the disk.

4. Closing Popovers with Click-Outside

The Manual Way

Country pickers, date pickers, autocomplete menus, and anything else that floats above the page have to close when the user clicks elsewhere. The textbook implementation listens on document:

function ManualPopover({ children }: { children: React.ReactNode }) {
  const [open, setOpen] = useState(false);
  const ref = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (!open) return;
    const handler = (e: MouseEvent) => {
      if (ref.current && !ref.current.contains(e.target as Node)) {
        setOpen(false);
      }
    };
    document.addEventListener("mousedown", handler);
    return () => document.removeEventListener("mousedown", handler);
  }, [open]);

  return (
    <div ref={ref} style={{ position: "relative" }}>
      <button onClick={() => setOpen((v) => !v)}>Toggle</button>
      {open && <div className="popover">{children}</div>}
    </div>
  );
}

This works for the simple case and breaks the moment your popover renders into a portal. The ref.current.contains(...) check assumes the popover is a DOM descendant of the trigger, which it usually is not for a real design system — popovers escape overflow containers by mounting at the body root. You also have to decide between mousedown and click (the right answer is almost always mousedown, so the popover closes before a downstream click handler fires), and remember to skip the listener when closed to avoid wasting cycles on every page click.

The ReactUse Way: useClickOutside

useClickOutside accepts a ref (or list of refs) and a handler:

import { useRef, useState } from "react";
import { useClickOutside } from "@reactuses/core";

function Popover({ children }: { children: React.ReactNode }) {
  const [open, setOpen] = useState(false);
  const triggerRef = useRef<HTMLDivElement>(null);
  const popoverRef = useRef<HTMLDivElement>(null);

  useClickOutside([triggerRef, popoverRef], () => setOpen(false));

  return (
    <>
      <div ref={triggerRef}>
        <button onClick={() => setOpen((v) => !v)}>Toggle</button>
      </div>
      {open && (
        <div ref={popoverRef} className="popover">
          {children}
        </div>
      )}
    </>
  );
}

The list-of-refs form is what makes this work for portaled popovers: you mark both the trigger and the floating panel as "inside," and clicks anywhere else fire the handler. The hook also handles the mousedown choice for you, attaches the listener once at the document level (no per-component churn), and cleans up on unmount.

There is a closely related hook, useClickAway, with a slightly different API for cases where you only need a single target ref — pick whichever reads better in your component.

Putting It All Together: A Settings Form

Here is a complete account-settings form that uses all four hooks. The username validates as you type. The whole form auto-saves to localStorage. The notifications switch is a controlled-or-uncontrolled component. The country picker is a portal-friendly popover that closes on outside click.

import { useEffect, useRef, useState } from "react";
import {
  useDebounce,
  useControlled,
  useLocalStorage,
  useClickOutside,
} from "@reactuses/core";

interface Settings {
  username: string;
  country: string;
  notifications: boolean;
}

const COUNTRIES = ["United States", "Japan", "Germany", "Brazil", "India"];

function NotificationSwitch({
  value,
  defaultValue = true,
  onChange,
}: {
  value?: boolean;
  defaultValue?: boolean;
  onChange?: (next: boolean) => void;
}) {
  const [on, setOn] = useControlled({ value, defaultValue, onChange });
  return (
    <button
      type="button"
      role="switch"
      aria-checked={on}
      onClick={() => setOn(!on)}
      style={{
        width: 48,
        height: 24,
        borderRadius: 999,
        border: "none",
        background: on ? "#3b82f6" : "#cbd5e1",
        position: "relative",
        cursor: "pointer",
      }}
    >
      <span
        style={{
          position: "absolute",
          top: 2,
          left: on ? 26 : 2,
          width: 20,
          height: 20,
          borderRadius: "50%",
          background: "white",
          transition: "left 120ms ease",
        }}
      />
    </button>
  );
}

function CountryPicker({
  value,
  onChange,
}: {
  value: string;
  onChange: (next: string) => void;
}) {
  const [open, setOpen] = useState(false);
  const triggerRef = useRef<HTMLButtonElement>(null);
  const menuRef = useRef<HTMLUListElement>(null);

  useClickOutside([triggerRef, menuRef], () => setOpen(false));

  return (
    <div style={{ position: "relative", display: "inline-block" }}>
      <button
        ref={triggerRef}
        type="button"
        onClick={() => setOpen((v) => !v)}
        style={{
          padding: "6px 12px",
          borderRadius: 6,
          border: "1px solid #cbd5e1",
          background: "white",
          cursor: "pointer",
        }}
      >
        {value || "Select country"} ▾
      </button>
      {open && (
        <ul
          ref={menuRef}
          style={{
            position: "absolute",
            top: "calc(100% + 4px)",
            left: 0,
            margin: 0,
            padding: 4,
            listStyle: "none",
            background: "white",
            border: "1px solid #cbd5e1",
            borderRadius: 8,
            boxShadow: "0 4px 12px rgba(0,0,0,0.08)",
            minWidth: 180,
          }}
        >
          {COUNTRIES.map((c) => (
            <li
              key={c}
              onClick={() => {
                onChange(c);
                setOpen(false);
              }}
              style={{
                padding: "6px 10px",
                borderRadius: 4,
                cursor: "pointer",
                background: c === value ? "#eff6ff" : "transparent",
              }}
            >
              {c}
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}

export default function SettingsForm() {
  const [settings, setSettings] = useLocalStorage<Settings>("account-settings", {
    username: "",
    country: "",
    notifications: true,
  });

  const debouncedUsername = useDebounce(settings.username, 400);
  const [status, setStatus] = useState<"idle" | "checking" | "ok" | "taken">("idle");

  useEffect(() => {
    if (!debouncedUsername) {
      setStatus("idle");
      return;
    }
    let cancelled = false;
    setStatus("checking");
    fetch(`/api/username?u=${encodeURIComponent(debouncedUsername)}`)
      .then((r) => r.json())
      .then((data) => {
        if (!cancelled) setStatus(data.available ? "ok" : "taken");
      })
      .catch(() => {
        if (!cancelled) setStatus("idle");
      });
    return () => {
      cancelled = true;
    };
  }, [debouncedUsername]);

  return (
    <form
      style={{
        maxWidth: 480,
        display: "grid",
        gap: 16,
        fontFamily: "system-ui, sans-serif",
      }}
      onSubmit={(e) => e.preventDefault()}
    >
      <label style={{ display: "grid", gap: 4 }}>
        <span style={{ fontSize: 14, color: "#475569" }}>Username</span>
        <input
          value={settings.username}
          onChange={(e) =>
            setSettings({ ...settings, username: e.target.value })
          }
          style={{
            padding: "8px 10px",
            borderRadius: 6,
            border: "1px solid #cbd5e1",
          }}
        />
        <span style={{ fontSize: 12, color: "#64748b" }}>
          {status === "checking" && "Checking..."}
          {status === "ok" && "✓ Available"}
          {status === "taken" && "✗ Taken"}
        </span>
      </label>

      <label style={{ display: "grid", gap: 4 }}>
        <span style={{ fontSize: 14, color: "#475569" }}>Country</span>
        <CountryPicker
          value={settings.country}
          onChange={(country) => setSettings({ ...settings, country })}
        />
      </label>

      <label
        style={{
          display: "flex",
          alignItems: "center",
          justifyContent: "space-between",
        }}
      >
        <span style={{ fontSize: 14, color: "#475569" }}>
          Email notifications
        </span>
        <NotificationSwitch
          value={settings.notifications}
          onChange={(notifications) =>
            setSettings({ ...settings, notifications })
          }
        />
      </label>
    </form>
  );
}

Four hooks, four responsibilities, zero overlap:

useDebounce turns rapid keystrokes into one delayed value, so async validation only fires after the user pauses
useControlled lets the switch component accept either a value prop or a defaultValue, without duplicating the branch logic
useLocalStorage persists the entire settings object across refreshes, with SSR-safe init and cross-tab sync
useClickOutside closes the country menu when the user clicks anywhere outside the trigger or the menu — including portaled rendering targets

The form file ends up roughly 200 lines of mostly markup. The fiddly browser plumbing — timer cleanup, SSR storage access, controlled-vs-uncontrolled detection, document-level listeners — lives inside library hooks that have already been tested across the patterns where teams usually get them wrong.

Installation

npm i @reactuses/core

Related Hooks

useDebounce — Lag a value behind its input by a fixed delay
useDebounceFn — Debounce a callback rather than a value
useControlled — Build components that accept either controlled or uncontrolled props
useLocalStorage — useState that persists to localStorage with SSR safety and cross-tab sync
useSessionStorage — Same shape as useLocalStorage, scoped to the session
useClickOutside — Detect clicks outside one or more elements
useClickAway — Single-ref variant of click-outside detection
useToggle — Boolean state with an explicit toggle setter
usePrevious — Read the previous value of a piece of state, useful for change detection in forms

ReactUse provides 100+ hooks for React. Explore them all →

Voice and Camera Input in React: Speech Recognition, Media Devices, and Permissions

reactuse.com — Thu, 07 May 2026 02:11:24 +0000

Voice and Camera Input in React: Speech Recognition, Media Devices, and Permissions

Voice and camera are the two senses that turn a static web app into something that feels alive. A search bar that you can talk to. A note-taking app that transcribes you in real time. A meeting tool that lets you pick which webcam to use. A walkie-talkie that talks when you hold a key. None of these are exotic anymore -- the browser has had the APIs for years -- but every one of them lives behind a gauntlet of permission prompts, vendor prefixes, and lifecycle quirks that make them painful to integrate into a React component.

This post walks through four browser capabilities for voice and camera input: live speech recognition with interim results, enumerating the user's cameras and microphones, querying permissions in a way that survives revocation, and using the Shift key as a push-to-talk modifier. As always, we will start with the manual implementation so you understand the plumbing, then swap it out for a focused hook from ReactUse. At the end, we will combine all four into a complete voice search component with a device picker, a permission gate, and a push-to-talk hold-to-record interaction.

1. Live Speech Recognition

The Manual Way

The Web Speech API is one of the older browser APIs that never really got standardized -- Chrome ships it as webkitSpeechRecognition, and the unprefixed SpeechRecognition is still missing in most engines. The minimal viable React wrapper looks like this:

function ManualSpeechRecognition() {
  const [transcript, setTranscript] = useState("");
  const [listening, setListening] = useState(false);
  const recognitionRef = useRef<any>(null);

  useEffect(() => {
    const SR =
      (window as any).SpeechRecognition ||
      (window as any).webkitSpeechRecognition;
    if (!SR) return;
    const recognition = new SR();
    recognition.continuous = true;
    recognition.interimResults = true;
    recognition.lang = "en-US";
    recognition.onresult = (event: any) => {
      const result = event.results[event.resultIndex];
      setTranscript(result[0].transcript);
    };
    recognition.onend = () => setListening(false);
    recognitionRef.current = recognition;
    return () => recognition.abort();
  }, []);

  const start = () => {
    recognitionRef.current?.start();
    setListening(true);
  };
  const stop = () => {
    recognitionRef.current?.stop();
    setListening(false);
  };

  return (
    <div>
      <button onClick={listening ? stop : start}>
        {listening ? "Stop" : "Start"} listening
      </button>
      <p>{transcript}</p>
    </div>
  );
}

This works, but it ignores the rough edges. There is no isFinal distinction, so the UI cannot tell when the user pauses (the difference between "interim" and "final" results is what makes voice UIs feel responsive). There is no error handling -- if the user denies microphone permission or there is no network, the transcript just silently never updates. There is no language negotiation. And SR typing is awful, because TypeScript does not ship types for webkitSpeechRecognition.

The ReactUse Way: useSpeechRecognition

useSpeechRecognition returns a clean object with the right primitives:

import { useSpeechRecognition } from "@reactuses/core";

function VoiceNote() {
  const { isSupported, isListening, isFinal, result, error, start, stop } =
    useSpeechRecognition({
      lang: "en-US",
      interimResults: true,
      continuous: true,
    });

  if (!isSupported) {
    return <p>Speech recognition is not supported in this browser.</p>;
  }

  return (
    <div>
      <button onClick={isListening ? stop : start}>
        {isListening ? "Stop" : "Start"} dictation
      </button>
      <p
        style={{
          fontStyle: isFinal ? "normal" : "italic",
          color: isFinal ? "#0f172a" : "#64748b",
        }}
      >
        {result || "Say something..."}
      </p>
      {error && <p style={{ color: "#ef4444" }}>Error: {error.error}</p>}
    </div>
  );
}

Things you get for free:

isFinal -- the hook tracks whether the current result is the speech engine's tentative guess (italicized in the example) or the locked-in transcript. This is the single biggest UX improvement over the naive version.
error object -- when permission is denied, the network drops, or the engine fails, you get a typed error you can show the user instead of silently freezing.
Hot config. start({ lang: "fr-FR" }) switches languages mid-session without requiring you to tear down the recognizer.
Cleanup on unmount. The hook calls abort() automatically, so navigating away never leaves the microphone hot.

The most powerful pattern is binding the result to a search input as the user speaks. Because the hook re-renders with each interim result, you can drive a live search query directly from spoken input and let the user see results as they talk.

2. Enumerating Cameras and Microphones

The Manual Way

Listing the user's audio and video devices requires navigator.mediaDevices.enumerateDevices(). There is a catch: until the user has granted permission to some device, the labels come back empty -- you get a list of deviceIds but no label like "FaceTime HD Camera". To get labels, you have to first call getUserMedia to trigger the permission prompt, then re-enumerate.

function ManualDeviceList() {
  const [devices, setDevices] = useState<MediaDeviceInfo[]>([]);

  useEffect(() => {
    let mounted = true;
    const refresh = async () => {
      try {
        // Trigger permission so labels are populated
        const stream = await navigator.mediaDevices.getUserMedia({
          audio: true,
          video: true,
        });
        stream.getTracks().forEach((t) => t.stop());
        const list = await navigator.mediaDevices.enumerateDevices();
        if (mounted) setDevices(list);
      } catch (e) {
        console.error(e);
      }
    };
    refresh();
    navigator.mediaDevices.addEventListener("devicechange", refresh);
    return () => {
      mounted = false;
      navigator.mediaDevices.removeEventListener("devicechange", refresh);
    };
  }, []);

  return (
    <ul>
      {devices.map((d) => (
        <li key={d.deviceId}>
          {d.kind}: {d.label || "(label hidden)"}
        </li>
      ))}
    </ul>
  );
}

That is the right shape, but you have to write the permission-trigger dance, the cleanup of the temporary stream, and the device-change listener every single time.

The ReactUse Way: useMediaDevices

useMediaDevices packages the whole thing:

import { useMediaDevices } from "@reactuses/core";

function CameraPicker({
  selected,
  onSelect,
}: {
  selected: string;
  onSelect: (id: string) => void;
}) {
  const [{ devices }, ensurePermissions] = useMediaDevices({
    requestPermissions: true,
    constraints: { video: true, audio: false },
  });

  const cameras = devices.filter((d) => d.kind === "videoinput");

  return (
    <div>
      <button onClick={() => ensurePermissions()}>Refresh devices</button>
      <select
        value={selected}
        onChange={(e) => onSelect(e.target.value)}
        style={{ marginLeft: 8 }}
      >
        {cameras.map((cam) => (
          <option key={cam.deviceId} value={cam.deviceId}>
            {cam.label || `Camera ${cam.deviceId.slice(0, 6)}`}
          </option>
        ))}
      </select>
    </div>
  );
}

The hook handles three things you would otherwise write yourself:

Permission negotiation. Pass requestPermissions: true and the hook will trigger getUserMedia on mount with the constraints you specify, then immediately stop the temporary tracks so the camera light goes off.
Live device list. The hook listens for devicechange and re-enumerates automatically -- if a user plugs in a new microphone or unplugs their headphones, the list updates with no extra code.
Manual refresh. The returned ensurePermissions lets you re-prompt at any time, useful if the user denied permission once and you want a "Try again" button.

The constraints argument is forwarded directly to getUserMedia, so you can ask only for video (and skip the awkward "do you want microphone access" prompt) when you only need to pick a camera.

3. Querying Permissions Properly

The Manual Way

Checking whether the user has already granted (or denied) microphone or camera permission, without triggering a prompt, requires the Permissions API. It is well-supported but verbose:

function ManualMicPermission() {
  const [state, setState] = useState<PermissionState | "unknown">("unknown");

  useEffect(() => {
    let mounted = true;
    let status: PermissionStatus | null = null;
    (async () => {
      try {
        status = await navigator.permissions.query({
          name: "microphone" as PermissionName,
        });
        if (mounted) setState(status.state);
        status.onchange = () => mounted && status && setState(status.state);
      } catch {
        // Permissions API not available for this name
      }
    })();
    return () => {
      mounted = false;
      if (status) status.onchange = null;
    };
  }, []);

  return <p>Microphone permission: {state}</p>;
}

Three things to notice. First, the API is callback-based via onchange, not React-friendly. Second, you have to feature-detect both the Permissions API itself and the specific name (some browsers do not support "microphone"). Third, the change listener has to be cleaned up explicitly, not via effect return.

The ReactUse Way: usePermission

usePermission reduces the entire dance to a single call:

import { usePermission } from "@reactuses/core";

function MicStatusBadge() {
  const state = usePermission("microphone");

  const color =
    state === "granted"
      ? "#10b981"
      : state === "denied"
      ? "#ef4444"
      : "#f59e0b";

  return (
    <span style={{ color, fontWeight: 600 }}>
      Microphone: {state || "unknown"}
    </span>
  );
}

The state is a React-native string that updates whenever the underlying permission status changes -- including out-of-band, when the user goes into browser settings and revokes the permission, your component's state will flip to "denied" without any action from you.

You can pass a string like "microphone" or "camera", or a full PermissionDescriptor object for permissions like "push" that need extra fields. The shape is identical to navigator.permissions.query, just turned into a hook.

4. Push-To-Talk With useKeyModifier

The Manual Way

A push-to-talk button is harder than it looks. You want to detect when the user is holding a key (say, the Space bar or the Shift key), start recording while it is held, and stop the moment they release it. You also have to handle the case where the user holds the key, switches focus to another window, releases the key while your tab is hidden, and then returns -- otherwise the recorder is stuck on.

function ManualPushToTalk() {
  const [pressed, setPressed] = useState(false);

  useEffect(() => {
    const onDown = (e: KeyboardEvent) => {
      if (e.code === "Space") setPressed(true);
    };
    const onUp = (e: KeyboardEvent) => {
      if (e.code === "Space") setPressed(false);
    };
    const onBlur = () => setPressed(false);
    window.addEventListener("keydown", onDown);
    window.addEventListener("keyup", onUp);
    window.addEventListener("blur", onBlur);
    return () => {
      window.removeEventListener("keydown", onDown);
      window.removeEventListener("keyup", onUp);
      window.removeEventListener("blur", onBlur);
    };
  }, []);

  return <p>{pressed ? "Recording..." : "Hold space to talk"}</p>;
}

This almost works. The bug: if the Space key auto-repeats while held (which it does on most operating systems), you will get a keydown followed by another keydown followed by an eventual keyup. You handled that. But if the user holds Shift instead and uses it as a modifier with another key combination, your manual tracking does not know about it.

The ReactUse Way: useKeyModifier

useKeyModifier exposes the OS-level modifier state (the same values you would get from event.getModifierState) as React state:

import { useKeyModifier } from "@reactuses/core";

function ShiftToRecord({ onTalkStart, onTalkEnd }: {
  onTalkStart: () => void;
  onTalkEnd: () => void;
}) {
  const shift = useKeyModifier("Shift");

  useEffect(() => {
    if (shift) onTalkStart();
    else onTalkEnd();
  }, [shift, onTalkStart, onTalkEnd]);

  return (
    <div
      style={{
        padding: 16,
        background: shift ? "#fef3c7" : "#f1f5f9",
        borderRadius: 8,
        textAlign: "center",
      }}
    >
      {shift ? "Recording (release Shift to stop)" : "Hold Shift to talk"}
    </div>
  );
}

The benefits over the keydown/keyup version:

OS-aware. The hook reads getModifierState, which queries the actual modifier state from the OS. It survives auto-repeat, focus loss, and weird key combinations correctly.
Works for any modifier. Pass "Control", "Alt", "Meta", "CapsLock", "NumLock" -- anything the browser tracks as a modifier.
Initial value. Configure initial: true if you want the React state to start as true (uncommon but useful for debugging).

Putting It All Together: A Voice Search With Device Picker

We will combine all four hooks into a single voice-driven search component. The user can pick which microphone to use, sees a permission badge, holds Shift to start dictating, and watches the transcript update live as they speak. When they release Shift, the final transcript becomes the search query.

import { useEffect, useState } from "react";
import {
  useSpeechRecognition,
  useMediaDevices,
  usePermission,
  useKeyModifier,
} from "@reactuses/core";

function VoiceSearch() {
  const [selectedMic, setSelectedMic] = useState<string>("");
  const [query, setQuery] = useState("");

  const micPermission = usePermission("microphone");
  const [{ devices }, requestDevices] = useMediaDevices({
    requestPermissions: false,
    constraints: { audio: true, video: false },
  });

  const microphones = devices.filter((d) => d.kind === "audioinput");

  const {
    isSupported,
    isListening,
    isFinal,
    result,
    error,
    start,
    stop,
  } = useSpeechRecognition({
    lang: "en-US",
    interimResults: true,
    continuous: false,
  });

  const shiftDown = useKeyModifier("Shift");

  // Push-to-talk: start when Shift is pressed, stop when released
  useEffect(() => {
    if (!isSupported || micPermission !== "granted") return;
    if (shiftDown) {
      start();
    } else if (isListening) {
      stop();
    }
  }, [shiftDown, isSupported, micPermission, start, stop, isListening]);

  // When recognition finalizes, commit the result to the query
  useEffect(() => {
    if (isFinal && result) {
      setQuery(result);
    }
  }, [isFinal, result]);

  const permissionColor =
    micPermission === "granted"
      ? "#10b981"
      : micPermission === "denied"
      ? "#ef4444"
      : "#f59e0b";

  return (
    <div
      style={{
        maxWidth: 640,
        padding: 24,
        background: "#ffffff",
        borderRadius: 16,
        boxShadow: "0 4px 24px rgba(15, 23, 42, 0.06)",
        fontFamily: "system-ui, sans-serif",
      }}
    >
      <header
        style={{
          display: "flex",
          justifyContent: "space-between",
          alignItems: "center",
          marginBottom: 16,
        }}
      >
        <h2 style={{ margin: 0, fontSize: 18 }}>Voice Search</h2>
        <span style={{ color: permissionColor, fontSize: 13, fontWeight: 600 }}>
          ● Mic: {micPermission || "unknown"}
        </span>
      </header>

      {!isSupported && (
        <p style={{ color: "#64748b" }}>
          This browser does not support speech recognition. Try Chrome.
        </p>
      )}

      {isSupported && micPermission !== "granted" && (
        <button
          onClick={requestDevices}
          style={{
            width: "100%",
            padding: 12,
            background: "#3b82f6",
            color: "white",
            border: "none",
            borderRadius: 8,
            cursor: "pointer",
          }}
        >
          Grant microphone access
        </button>
      )}

      {isSupported && micPermission === "granted" && (
        <>
          <div style={{ display: "flex", gap: 12, marginBottom: 12 }}>
            <select
              value={selectedMic}
              onChange={(e) => setSelectedMic(e.target.value)}
              style={{
                flex: 1,
                padding: 8,
                borderRadius: 6,
                border: "1px solid #cbd5e1",
              }}
            >
              <option value="">Default microphone</option>
              {microphones.map((mic) => (
                <option key={mic.deviceId} value={mic.deviceId}>
                  {mic.label || `Mic ${mic.deviceId.slice(0, 6)}`}
                </option>
              ))}
            </select>
          </div>

          <div
            style={{
              padding: 16,
              background: shiftDown ? "#dcfce7" : "#f8fafc",
              borderRadius: 8,
              border: shiftDown
                ? "2px solid #10b981"
                : "2px dashed #cbd5e1",
              textAlign: "center",
              transition: "all 120ms ease",
            }}
          >
            <p style={{ margin: 0, fontWeight: 600, fontSize: 13 }}>
              {shiftDown ? "Listening..." : "Hold Shift to dictate"}
            </p>
            {result && (
              <p
                style={{
                  margin: "8px 0 0",
                  fontStyle: isFinal ? "normal" : "italic",
                  color: isFinal ? "#0f172a" : "#64748b",
                }}
              >
                {result}
              </p>
            )}
          </div>

          {error && (
            <p style={{ color: "#ef4444", fontSize: 13, marginTop: 8 }}>
              Recognition error: {error.error}
            </p>
          )}

          <input
            value={query}
            onChange={(e) => setQuery(e.target.value)}
            placeholder="Search query..."
            style={{
              width: "100%",
              marginTop: 12,
              padding: 10,
              borderRadius: 6,
              border: "1px solid #cbd5e1",
              fontSize: 16,
            }}
          />
        </>
      )}
    </div>
  );
}

Four hooks, four orthogonal concerns:

usePermission drives the badge in the header and gates the rest of the UI behind the user's actual decision. Because it is reactive, if the user revokes mic access in browser settings, the badge updates and the input vanishes automatically.
useMediaDevices populates the microphone picker without forcing a permission prompt unless the user clicks "Grant".
useSpeechRecognition does the actual transcription, distinguishes interim from final results, and surfaces engine errors in a typed way.
useKeyModifier turns the Shift key into a push-to-talk trigger that survives focus loss, OS auto-repeat, and weird key combinations.

The component is roughly 130 lines, the vast majority of which is markup. The browser-API plumbing -- the parts that historically take the longest to get right -- is one import line per concern.

A Note on Testing

Voice and camera features are notoriously hard to test because the browser APIs they depend on require human gestures and physical hardware. The hooks all expose isSupported flags so your test environments (jsdom, Vitest, Storybook with mocked navigators) can branch cleanly on the absence of the underlying APIs and render fallback states. If you are building a serious voice UI, dedicate a small layer of integration tests that run in headless Chrome with a fake media stream -- that is the only way to catch the real bugs.

Installation

npm i @reactuses/core

Related Hooks

useSpeechRecognition -- Live speech-to-text with interim and final result tracking
useMediaDevices -- Enumerate cameras and microphones with permission handling
usePermission -- Reactively query the Permissions API for any permission name
useKeyModifier -- Track OS-level modifier key state (Shift, Control, etc.)
useSupported -- Reactively check whether a browser API is available
useEventListener -- Attach event listeners declaratively for custom voice flows
useObjectUrl -- Create temporary URLs for recorded audio blobs to preview them

ReactUse provides 100+ hooks for React. Explore them all →

The SSR State Management Trap: defineStore vs defineContextStore

reactuse.com — Wed, 06 May 2026 04:04:42 +0000

You ship a Next.js-style SSR app with a global user store. A month later, a user files a bug: "I logged in and saw someone else's profile." You can't reproduce it locally. Production logs are useless. The session cookie looks fine.

What happened: your global store is a singleton on the server. Under concurrent requests, one request's setUser() wrote to the same object another request was reading. The second user hit a warm server, got a hydration payload containing the first user's data, and saw it for a split second before React reconciled.

This is the SSR state management trap. It's one of the oldest footguns in server rendering, and almost every framework makes it possible. In this post: how it happens at the module level, how Pareto's defineStore and defineContextStore address it, and the decision rule for which one to use.

Why global state leaks across requests on the server

In the browser, your app is one process per user. A module-level variable is a per-user variable — there's no one else sharing it.

On the server, one Node process serves thousands of users. A module-level variable is shared across every request. If request A mutates it during its render, and request B reads it during its render, B sees A's state.

// state.ts (imported by server and client)
let currentUser = null

export function setCurrentUser(user) { currentUser = user }
export function getCurrentUser() { return currentUser }

Works in the browser. On the server, two requests racing through:

t=0ms:  Request A starts, calls setCurrentUser({ id: 'alice' })
t=1ms:  Request B starts, calls setCurrentUser({ id: 'bob' })
t=2ms:  Request A reads getCurrentUser() → { id: 'bob' }  ← leaked

Alice's rendered HTML contains Bob's name. Alice's hydration payload contains Bob's data. Whatever the server sends to Alice's browser now references Bob.

This doesn't require a state library. A global Map, a module.cache, a let declaration — all vulnerable. State libraries just dress up the same pattern.

What Pareto's two store types do

Pareto has two APIs that look almost identical but have opposite SSR behavior.

defineStore — one instance per process

import { defineStore } from '@paretojs/core/store'

const themeStore = defineStore((set) => ({
  mode: 'light' as 'light' | 'dark',
  toggle: () => set((d) => {
    d.mode = d.mode === 'light' ? 'dark' : 'light'
  }),
}))

On the server, there's one themeStore per Node process. Every SSR request reads and writes the same state. This is the dangerous primitive.

On the client, there's one themeStore per browser tab — which is what you actually want for client-side state.

defineContextStore — one instance per React render

import { defineContextStore } from '@paretojs/core/store'

const { Provider, useStore } = defineContextStore((initialUser) => (set) => ({
  user: initialUser,
  setUser: (user) => set((d) => { d.user = user }),
}))

Context stores are scoped to a <Provider>. Each SSR request renders its own provider tree, gets its own store instance, and can't see any other request's state.

function App({ user }) {
  return (
    <Provider initialData={user}>
      <Dashboard />
    </Provider>
  )
}

Two concurrent requests create two isolated stores. Alice's render never touches Bob's store. The pattern is guaranteed safe.

The decision rule

Ask: "Does the initial state of this store differ per user or per request?"

Yes — use defineContextStore. User identity, auth tokens, per-tenant config, feature flags that depend on the viewer, shopping cart tied to a session.
No — defineStore is fine. UI theme, sidebar open/closed, recently-viewed modals, client-side caches keyed on data that's already safe to share.

For the "no" case, the reasoning is: if every SSR request reads the same initial state, there's nothing for concurrent requests to leak to each other. The theme is 'light' for every new request until JavaScript hydrates and the client reads localStorage. No per-request state, no leak surface.

If you're ever unsure, pick defineContextStore. It's always safe. You can downgrade to defineStore later once you've confirmed the state is truly request-independent.

A leaky example and its fix

Here's a realistic pattern that leaks:

// ❌ Bad: user identity in a global store
import { defineStore } from '@paretojs/core/store'

export const userStore = defineStore((set) => ({
  user: null as User | null,
  setUser: (user: User) => set((d) => { d.user = user }),
  isAdmin: false,
}))

Then in a loader or layout:

// ❌ Mutating a global store during SSR
export async function loader(ctx: LoaderContext) {
  const user = await getUserFromSession(ctx.request)
  userStore.setState((d) => {
    d.user = user
    d.isAdmin = user.role === 'admin'
  })
  return { user }
}

This leaks in both directions. Concurrent requests overwrite d.user. Requests that arrive after a previous user's session read stale data. The bug looks like random user-mixup reports.

The fix:

// ✅ Good: context store, scoped to the render
import { defineContextStore } from '@paretojs/core/store'

export const { Provider: UserProvider, useStore: useUser } =
  defineContextStore((initial: { user: User; isAdmin: boolean }) => (set) => ({
    user: initial.user,
    isAdmin: initial.isAdmin,
    setUser: (user: User) => set((d) => { d.user = user }),
  }))

Wrap the app in a provider in the root layout:

// app/layout.tsx
import { UserProvider } from './stores/user'

export default function RootLayout({ children, loaderData }) {
  const { user, isAdmin } = loaderData as LoaderData
  return (
    <UserProvider initialData={{ user, isAdmin }}>
      {children}
    </UserProvider>
  )
}

Now every request gets its own store instance, initialized from its own loader data. No shared object. No leak path.

When defineStore is the right call

Not every store is dangerous. Plenty of client-state is genuinely the same on every SSR request and only diverges after hydration.

UI preferences

export const uiStore = defineStore((set) => ({
  sidebarOpen: true,
  commandPaletteOpen: false,
  toggleSidebar: () => set((d) => { d.sidebarOpen = !d.sidebarOpen }),
}))

On the server, every request starts with sidebarOpen: true. No user data, no request-dependent initial state. Safe.

Client-only feature toggles

export const devStore = defineStore((set) => ({
  showDebugOverlay: false,
  toggleDebugOverlay: () => set((d) => { d.showDebugOverlay = !d.showDebugOverlay }),
}))

Debug UI that only the developer uses. Initial state is identical for every request; all mutations happen on the client.

The "I'll just reset it at the start of each request" trick

A pattern people try when they realize globals leak: reset the store at the start of every SSR request.

// ❌ Doesn't work
export async function loader(ctx) {
  userStore.setState(() => ({ user: null, isAdmin: false }))
  const user = await getUserFromSession(ctx.request)
  userStore.setState((d) => { d.user = user })
  return { user }
}

This has two problems:

Reset and populate are not atomic. Another request can interleave between them and see the reset state — or the first request's populated state before its own reset.
Multiple renders share one store. Pareto's streaming SSR holds a response open while deferred promises resolve. During that window, another request can run through the same loader and overwrite the store.

The "reset per request" pattern is what AsyncLocalStorage exists to solve, and what context stores are in Pareto. Don't try to work around it with manual resets.

What about Zustand / Jotai / Redux?

Same principle. If the library's default API is a module-level store, it's unsafe on the server. Most of these libraries document an "SSR mode" that requires you to instantiate a per-request store and pass it through context.

Pareto's defineContextStore is that pattern as a first-class API. If you're coming from Zustand, defineContextStore is the shape you already know from Zustand's createStore + React context wrapper — just built in.

Pareto's defineStore is the global-singleton shortcut for cases where you've verified the shortcut is safe.

The bigger pattern

SSR adds a dimension most state management libraries weren't originally designed for. The browser gave you "one app, one state tree, forever." The server gives you "one process, many concurrent state trees, for a few milliseconds each." Any API that pretends these are the same will eventually leak.

Pareto's answer: two APIs with different defaults.

defineStore for state where "one process, one state" is genuinely what you want
defineContextStore for state where "each render tree, its own state" is what you need

Pick the one that matches the shape of the state. If you can't decide, defineContextStore is never wrong.

npx create-pareto@latest my-app
cd my-app && npm install && npm run dev

Pareto is a lightweight, streaming-first React SSR framework built on Vite. Documentation