DEV Community: ReactUse

React useTimeout Hook: Declarative setTimeout with Cleanup (2026)

ReactUse — Fri, 21 Aug 2026 02:41:25 +0000

Here is a "Copied!" button. Every codebase has one, and this version has three bugs:

function CopyButton({ text }: { text: string }) {
  const [copied, setCopied] = useState(false);

  useEffect(() => {
    if (!copied) return;
    setTimeout(() => setCopied(false), 2000);
  }, [copied]);

  return (
    <button onClick={() => { navigator.clipboard.writeText(text); setCopied(true); }}>
      {copied ? "Copied!" : "Copy"}
    </button>
  );
}

It never clears the timer, so unmounting mid-countdown leaves a callback scheduled against a dead component. It re-arms on every copied change instead of restarting cleanly. And in React 18's StrictMode the effect runs twice on mount, so you get two timers where you meant one. Add the missing clearTimeout and you've fixed the leak but not the shape of the problem: the timer's lifetime is now tangled into a dependency array, and there is still no way to cancel it from a click handler, restart it on demand, or ask "is it still running?"

setTimeout is a fire-and-forget browser primitive. React components are not fire-and-forget — they unmount, re-render, and change their minds. useTimeout and useTimeoutFn from @reactuses/core close that gap by handing you the timer as a piece of state plus two controls, instead of a number you have to babysit. This post covers what they actually do under the hood, the one behavior that trips everyone up (the delay is a dependency, the callback isn't), a start() trap that silently corrupts your arguments, and the patterns worth copying.

Quick Start

npm install @reactuses/core

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

function CopyButton({ text }: { text: string }) {
  const [copied, setCopied] = useState(false);
  const [, startReset] = useTimeoutFn(() => setCopied(false), 2000, {
    immediate: false,
  });

  return (
    <button
      onClick={async () => {
        await navigator.clipboard.writeText(text);
        setCopied(true);
        startReset();
      }}
    >
      {copied ? "Copied!" : "Copy"}
    </button>
  );
}

No effect, no dependency array, no cleanup to remember. The timer is armed by a click rather than by a render, it's cleared automatically on unmount, and clicking Copy again while the badge is still showing restarts the two seconds instead of stacking a second timer on top of the first.

Two Hooks, One Engine

Both hooks return the same three-element tuple — the library calls it Stoppable:

type Stoppable = [isPending: boolean, start: Fn, cancel: Fn];

They differ only in what happens at the deadline.

useTimeoutFn(cb, ms, options?) runs your callback. Use it when the deadline has a job to do — dismiss the toast, reset the flag, fire the analytics ping.

useTimeout(ms?, options?) runs no callback of yours. It flips isPending from true to false and re-renders. Use it when the deadline is the state — "has 300ms passed yet?" is the whole question.

useTimeout is literally useTimeoutFn with the callback slot spent on a forced re-render:

export const useTimeout: UseTimeout = (ms = 0, options = {}) => {
  const update = useUpdate();
  return useTimeoutFn(update, ms, options);
};

That useUpdate is a two-line useReducer that increments a counter modulo a million — the standard "force a re-render without inventing fake state" trick, with the modulo there so a long-lived component can't drift toward Number.MAX_SAFE_INTEGER. It guarantees a render at the deadline even in the cases where isPending alone wouldn't produce one, which is what lets you use useTimeout as a bare "re-render me in N milliseconds" primitive when you need to re-read something that isn't React state.

By default both start on mount. Pass { immediate: false } and nothing happens until you call start() yourself.

What It Actually Does

The implementation is about twenty lines, and every one of them is answering a bug from the opening example:

export const useTimeoutFn = (cb, interval, options = {}) => {
  const { immediate = true } = options;
  const [pending, setPending] = useState(() => immediate);
  const savedCallback = useLatest(cb);
  const timer = useRef<ReturnType<typeof setTimeout>>();

  const stop = useEvent(() => {
    setPending(false);
    if (timer.current) clearTimeout(timer.current);
  });

  const start = useEvent((...args: unknown[]) => {
    clearTimeout(timer.current);
    timer.current = setTimeout(() => {
      setPending(false);
      savedCallback.current(...args);
    }, interval);
    setPending(true);
  });

  useEffect(() => {
    if (immediate) start();
    return stop;
  }, [stop, immediate, interval, start]);

  return [pending, start, stop];
};

Five decisions are packed in there, and each one is worth knowing about because each one shows up in your code later.

The callback lives in a ref, not in the deps. useLatest keeps savedCallback.current pointing at the newest function after every committed render, and the timer calls through it. So the closure that fires at the deadline is the one from your most recent render — the stale-closure bug is gone — but swapping the callback does not restart the countdown. A timer started 4 seconds into a 5-second delay still has 1 second left, even if the function it will call has been re-created ten times since. That's the correct behavior and it's covered by a test in the repo, but it surprises people who expect a useEffect-shaped hook to re-run when its inputs change.

The delay is in the deps. interval sits in the dependency array, so changing it tears the timer down and starts a fresh one from zero. Deliberate, and usually what you want — but see the gotchas, because a delay computed inline is an easy way to build a countdown that never finishes.

start and stop never change identity. useEvent wraps both in a useCallback with an empty dependency array that forwards to a ref, so the functions you get on render 1 are reference-identical to the ones on render 500. You can put them in dependency arrays, hand them to memoized children, or stash them in a context without any of the usual churn.

start() clears before it sets. Calling it while a timer is already running doesn't stack — it cancels and restarts. That's what makes "click Copy again" behave sanely, and it means repeatedly calling start() on every keystroke gives you debounce semantics for free (though useDebounceFn says what you mean more clearly).

pending is seeded, not flashed. useState(() => immediate) means that when immediate is on, the very first render already reads true — no false → true flicker on mount, no wasted render. And because immediate is a plain option with the same value on the server and the client, the seeded value is identical on both sides. Nothing in this hook touches window, document or Date, so it renders on the server without a guard and hydrates without a mismatch.

The effect's cleanup is stop itself, which is the leak fix: unmount clears the timer, always, whatever state it was in.

The Patterns Worth Copying

The delayed spinner

The single best use of useTimeout. A spinner that appears for 80ms and vanishes reads as a flicker — worse than no spinner at all. The fix is to only show it if loading is actually slow, which is exactly "has 300ms passed?":

function UserList() {
  const { data, isLoading } = useUsers();
  const [tooSoon] = useTimeout(300);

  if (isLoading) return tooSoon ? null : <Spinner />;
  return <List items={data} />;
}

tooSoon starts true and flips to false 300ms after mount. Fast responses render nothing at all in the gap; slow ones get a spinner. One line, no state, no effect.

Auto-dismiss with hover-to-pause

The tuple's cancel and start are what make this trivial — a hand-rolled version needs a ref and two effects:

function Toast({ message, onDismiss }: { message: string; onDismiss: () => void }) {
  const [, start, cancel] = useTimeoutFn(onDismiss, 5000);

  return (
    <div role="status" onMouseEnter={cancel} onMouseLeave={() => start()}>
      {message}
    </div>
  );
}

Note the () => start() on onMouseLeave. That is not a style choice — see the gotchas.

A cooldown button

function ResendCodeButton({ onResend }: { onResend: () => void }) {
  const [cooling, startCooldown] = useTimeout(30_000, { immediate: false });

  return (
    <button
      disabled={cooling}
      onClick={() => { onResend(); startCooldown(); }}
    >
      {cooling ? "Code sent — try again shortly" : "Resend code"}
    </button>
  );
}

immediate: false is the important part: the button is live on mount and only goes cold once it's been used. If you want to render the remaining seconds rather than a boolean, that's a different hook — useCountDown ticks down and hands you the number.

Yielding to the browser

useTimeout() with no arguments defaults to ms = 0, which still defers to a macrotask — after paint, after pending microtasks. Occasionally that's exactly the escape hatch you want for "let the browser draw this frame before I do the expensive thing," and it's cheaper to reason about than a requestIdleCallback polyfill. For anything that should run per-frame instead of once, use useRafFn.

Gotchas Worth Knowing

start forwards its arguments to your callback. This is a real feature — start(userId) passes userId through to the timer callback — and a real trap when the caller is a DOM handler. onMouseLeave={start} hands React's synthetic MouseEvent straight into your onDismiss(...). If that callback is onDismiss(id?: string), you've just dismissed a toast with an event object as its id, and TypeScript won't stop you because start is typed as Fn. Wrap it: onMouseLeave={() => start()}. Same rule for onClick, onBlur, and anything else that supplies an event.
A changing delay restarts the countdown — every time. interval is a dependency, so this never fires:

  // BROKEN: a new delay on every render restarts the timer forever
  useTimeoutFn(onDone, Math.max(0, deadline - Date.now()));

Any delay recomputed per render resets the clock before it can run out. Pass a stable number, or memoize it. The flip side is useful: when the delay genuinely changes — a user picking "dismiss after 3s / 10s / never" — the restart is exactly right.

A changing callback does not restart it. The mirror image, and equally worth internalizing. Your callback is always the latest one, but its scheduled deadline is whatever it was when start() ran.
cancel() sets isPending to false. It's a stop, not a pause — there is no "resume with the remaining time." start() after cancel() begins a fresh full delay. If you need true pause/resume semantics, track the elapsed time yourself and pass the remainder as the new delay.
After unmount, isPending freezes at its last rendered value. The cleanup calls stop(), which clears the timer and calls setPending(false) — but that state update lands on an unmounted component, so React discards it. If you snapshot the tuple in a test and read it after unmount(), isPending will still be true. It is not a leak and not a warning; the timer really is cleared.
StrictMode double-arms, then converges. In React 18 development the mount effect runs, cleans up, and runs again, so you'll see two setTimeout calls in dev. There's never a duplicate firing — stop clears the first one and start clears again before scheduling — but the countdown effectively begins on the second run. In practice that's a sub-millisecond difference; in a test with fake timers advanced by exact amounts, it's a difference that can bite.
immediate is read on mount and as a dependency. Flipping immediate from false to true on a later render will start the timer, because it's in the effect's deps. Toggling it is a legitimate way to arm a timer declaratively — just don't be surprised when it's not inert.

When Not to Use It

These hooks are a thin, honest wrapper over one setTimeout. When your problem has a name, the named hook handles edge cases you'd otherwise rediscover:

Repeating on a schedule → useInterval, not a timeout that re-arms itself. Self-rescheduling timeouts drift and are miserable to cancel.
"Wait until the user stops typing" → useDebounceFn for a callback, useDebounce for a value. You can build this by calling start() on each keystroke, but the dedicated hooks say so at a glance.
"At most once every N ms" → useThrottleFn / useThrottle. A timeout is the wrong primitive for rate limiting; the first call should go through immediately.
A visible countdown → useCountDown. Rendering "4… 3… 2…" from a single timeout means running your own tick loop.
"Has the user gone quiet?" → useIdle, which already watches the right set of activity events.
Per-frame animation → useRafFn. setTimeout doesn't align to the compositor and keeps running in background tabs.
Cleanup on unmount only → useUnmount. No timer needed.

Takeaways

setTimeout in a useEffect forces you to hand-manage four things at once: the cleanup, the dependency array, the stale closure, and the lack of controls. Getting three right and one wrong is the normal outcome.
useTimeoutFn returns [isPending, start, cancel] and clears on unmount by construction. useTimeout is the same engine with the callback spent on a re-render, for when the deadline itself is the state you care about.
The delay is a dependency and the callback isn't — changing the delay restarts the countdown, changing the callback silently swaps what fires. Both are deliberate; knowing which is which saves an afternoon.
start forwards its arguments, so never pass it directly to a DOM event handler. onMouseLeave={() => start()}, not onMouseLeave={start}.
start and cancel are identity-stable forever, isPending is seeded so it doesn't flash on mount, and nothing in the hook touches a browser global — it renders on the server untouched.

useTimeout, useTimeoutFn, useInterval, and 110+ other SSR-safe, TypeScript-first hooks live in @reactuses/core — one install, tree-shakeable, no dependencies to babysit.

npm install @reactuses/core

React useEventListener Hook: Type-Safe DOM Events (2026)

ReactUse — Thu, 20 Aug 2026 09:23:19 +0000

Here's a modal close-on-Escape that quietly does the wrong thing:

function Modal({ onClose }: { onClose: () => void }) {
  useEffect(() => {
    const onKey = (e: KeyboardEvent) => {
      if (e.key === "Escape") onClose();
    };
    window.addEventListener("keydown", onKey);
    return () => window.removeEventListener("keydown", onKey);
  }, [onClose]);

  return <div role="dialog">…</div>;
}

If the parent passes an inline onClose={() => setOpen(false)} — and it almost always does — onClose is a new function on every render, so this effect tears the listener down and adds a fresh one on every single render of the parent. Drop onClose from the deps to stop the churn and you get the other bug: the listener now holds the first render's onClose forever, and closing the modal calls a stale closure.

You can't win this with a dependency array, because the two things you want are in direct conflict: subscribe once, but always run the newest handler. The fix is to separate them — register the listener on a stable identity, and call through a ref that's kept current. useEventListener from @reactuses/core is that split, packaged. This post covers what it actually does under the hood, the four ways to name a target, exactly what TypeScript infers for each one (this part surprises people), the options that don't retrigger, and the two gotchas worth knowing before you ship it.

Quick Start

npm install @reactuses/core

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

function Modal({ onClose }: { onClose: () => void }) {
  useEventListener("keydown", (e) => {
    if (e.key === "Escape") onClose();
  });

  return <div role="dialog">…</div>;
}

That's the whole fix. No dependency array, no useCallback on the parent, no cleanup to remember. The listener is added to window once when the component mounts and removed when it unmounts; the arrow function you passed is re-created on every render and it doesn't matter, because the listener never re-registers — it calls the latest one. e is a KeyboardEvent, inferred, not annotated.

The signature is four arguments, three of them optional:

useEventListener(eventName, handler, target?, options?);

target defaults to window. options is the same boolean | AddEventListenerOptions you'd pass to addEventListener.

What It Actually Does

The implementation is short enough to read in full, and worth reading because every line is answering one of the problems above:

function useEventListener(eventName, handler, element, options = {}) {
  const savedHandler = useLatest(handler);
  const { key: elementKey, ref: elementRef } = useStableTarget(element, defaultWindow);

  useDeepCompareEffect(() => {
    const targetElement = getTargetElement(elementRef.current, defaultWindow);
    if (!(targetElement && targetElement.addEventListener)) return;

    const eventListener = (event) => savedHandler.current(event);
    on(targetElement, eventName, eventListener, options);

    return () => off(targetElement, eventName, eventListener);
  }, [eventName, elementKey, options]);
}

Four decisions are packed in there:

The handler is held in a ref, not in the deps. useLatest keeps savedHandler.current pointing at the newest handler after every committed render, and the function actually registered with the DOM is a thin wrapper that forwards to it. So the handler you pass can be a brand-new closure every render — inline arrow functions are not just allowed, they're the expected usage — while addEventListener is called exactly once. That's the "subscribe once, run the newest" split, and it's why handler is deliberately absent from the dependency list.

The dependency list is deep-compared. The effect is useDeepCompareEffect, not useEffect, so a fresh-but-identical options object each render doesn't count as a change. Writing useEventListener("scroll", onScroll, ref, { passive: true }) with the object literal inline is fine: three renders, one addEventListener call. Change the contents to { passive: false } and it does re-register, which is what you want.

The target is resolved inside the effect, at commit time. getTargetElement runs in the effect body rather than during render, so a ref target has already been populated by React — ref.current is null while rendering and only becomes a node in the commit phase. This is the difference between the listener attaching and silently doing nothing.

On the server it's a no-op. The export is isBrowser ? implementation : noop, so nothing touches window during SSR and there's no typeof window === "undefined" guard for you to write. Listeners attach after hydration, in the effect, like every other browser subscription.

The Four Ways to Name a Target

target accepts four shapes, and picking the right one is most of the API:

// 1. omitted → window
useEventListener("resize", () => setWidth(window.innerWidth));

// 2. a function returning an element → document, or anything you look up lazily
useEventListener("visibilitychange", () => setActive(!document.hidden), () => document);

// 3. a ref
const boxRef = useRef<HTMLDivElement>(null);
useEventListener("wheel", (e: WheelEvent) => e.preventDefault(), boxRef, { passive: false });

// 4. any EventTarget you already hold
useEventListener("message", (e: MessageEvent) => handle(e.data), worker);

Case 2 exists because document isn't available during module evaluation on the server, and because passing document directly would be a new-identity-every-render problem for anything looked up on the fly. The wrapper function is resolved at commit time and its result is what the effect keys on, so () => document is stable in the way that matters.

Case 4 is the one people forget: EventTarget is not just DOM elements. A Worker, a WebSocket, an EventSource, a MediaQueryList, window.visualViewport, a BroadcastChannel, an <audio> element, navigator.serviceWorker, even an AbortSignal — all of them are event targets, and all of them work here with the same automatic cleanup. (For the common ones, the library already ships purpose-built hooks: useEventSource, useBroadcastChannel, useMediaQuery, useNetwork.)

What TypeScript Actually Infers

This is the part worth being precise about, because the hook ships six overloads and they don't all give you the same thing. Verified against the current types:

Target form	`e` is inferred as
omitted (`window`)	the exact `WindowEventMap` type — `"keydown"` → `KeyboardEvent` ✅
a raw `HTMLElement` / `Element` / `Document`	the exact event type — `"click"` → `MouseEvent` ✅
a ref object	`any` ⚠️
a function target (`() => document`)	`any` ⚠️

The two any cases fall through to the general overload, which types the handler as (...p: any) => void. Nothing breaks — but you lose the autocomplete and the type checking exactly where refs are most common. The fix is one annotation, and it costs nothing:

// ⚠️ e is any
useEventListener("click", (e) => console.log(e.clientX), buttonRef);

// ✅ e is MouseEvent, checked
useEventListener("click", (e: MouseEvent) => console.log(e.clientX), buttonRef);

Two related sharp edges in the same area. First, e is the native DOM event, not React's SyntheticEvent — e.target is not typed for you, e.currentTarget is EventTarget | null, and there's no pooling to worry about. Second, the event name is only constrained when the target is one of the typed overloads; with a ref or function target the name is a plain string, so a typo like "keydwon" compiles happily and attaches a listener that never fires. If a listener seems dead, check the spelling before you check anything else.

Patterns

Keyboard shortcuts

The canonical window listener. One hook per shortcut, or one handler with a switch — both are fine, because neither re-registers:

function useShortcut(combo: (e: KeyboardEvent) => boolean, run: () => void) {
  useEventListener("keydown", (e) => {
    if (combo(e)) {
      e.preventDefault();
      run();
    }
  });
}

function CommandBar() {
  const [open, setOpen] = useState(false);
  useShortcut((e) => (e.metaKey || e.ctrlKey) && e.key === "k", () => setOpen(true));
  useShortcut((e) => e.key === "Escape", () => setOpen(false));
  // …
}

Note the composition: useEventListener is a fine primitive to build your hooks on, and because the handler is ref-held, run and combo can be inline closures over fresh state without any memoization ceremony. If you only need the modifier keys themselves, useKeyModifier already tracks them.

Non-passive wheel and touch listeners

This is the case JSX props genuinely cannot do. React attaches onWheel and onTouchStart as passive listeners at the root, so calling e.preventDefault() inside them logs a console warning and does nothing. To actually block a scroll or a pinch you need a real listener registered with { passive: false } on the element:

function ZoomCanvas() {
  const canvasRef = useRef<HTMLDivElement>(null);
  const [zoom, setZoom] = useState(1);

  useEventListener(
    "wheel",
    (e: WheelEvent) => {
      if (!e.ctrlKey) return;
      e.preventDefault(); // works — this listener is genuinely non-passive
      setZoom((z) => clamp(z * (1 - e.deltaY / 500), 0.5, 4));
    },
    canvasRef,
    { passive: false },
  );

  return <div ref={canvasRef} style={{ transform: `scale(${zoom})` }} />;
}

The mirror image is just as useful: mark a high-frequency scroll or touchmove listener { passive: true } so the browser knows it never needs to wait on your handler before scrolling.

Window and document events React doesn't give you props for

resize, online/offline, visibilitychange, beforeunload, hashchange, storage, paste at the document level — none of these have a JSX equivalent, and all of them are one line:

function useOnlineStatus() {
  const [online, setOnline] = useState(true);
  useEventListener("online", () => setOnline(true));
  useEventListener("offline", () => setOnline(false));
  return online;
}

Before you write these by hand, check whether the library already has them — useWindowSize, useOnline, useDocumentVisibility, usePageLeave, useTextSelection are all thin wrappers over exactly this hook, with the state management already done.

Rate-limiting a hot event

scroll, mousemove, resize and pointermove fire far faster than you want to re-render. Wrap the handler, not the listener:

function ScrollSpy() {
  const [y, setY] = useState(0);
  const onScroll = useThrottleFn(() => setY(window.scrollY), 100);
  useEventListener("scroll", onScroll);
  return <progress value={y} max={document.body.scrollHeight} />;
}

useThrottleFn for "at most every N ms", useDebounceFn for "once the user stops". Both keep a stable identity, so the listener still registers once. For scroll position specifically, useScroll and useWindowScroll already do this properly.

Gotchas Worth Knowing

A ref target keys on the ref, not on ref.current. The effect's dependency is the ref object, which is stable for the component's lifetime, so if the DOM node behind the ref is replaced — a conditional branch that mounts a genuinely different element, a key change, a list reorder — the listener stays attached to the old, detached node and never moves. React usually reuses the same DOM node when the element type and position match, which is why this rarely bites, but when it does it's baffling. The fix is to make the node the dependency by holding it in state with a callback ref:

  const [node, setNode] = useState<HTMLElement | null>(null);
  useEventListener("click", (e: MouseEvent) => handle(e), node);
  return show ? <button ref={setNode}>A</button> : <span ref={setNode}>B</span>;

Now the target identity changes when the node does, and the listener re-registers on the new element.

Listeners attach after paint, not during render. It's an effect, so between first paint and the effect running there is a window — usually a frame — where the listener isn't there yet. Irrelevant for user-driven events (nobody presses a key that fast), but it means you cannot use this to catch an event that fires during mount. If an element needs a listener from its very first paint, that's what layout effects and JSX props are for.
Passing document or an element directly is fine — until it's conditional. useEventListener("click", h, someState ? elA : elB) re-registers when the element changes, which is correct. But useEventListener("click", h, document.getElementById("x")) runs a DOM query on every render and returns null on the server; prefer the function form () => document.getElementById("x").
It doesn't return an off() handle. Unlike VueUse's version, there's no manual stop function — the lifetime is the component's. If you need to start and stop a listener on demand, gate it inside the handler with a ref or a piece of state (if (!enabledRef.current) return), which is cheaper than re-registering anyway.
One hook, one event. There's no array form. useEventListener("mousedown", h) and useEventListener("touchstart", h) as two calls is the idiom — hooks are cheap, and it keeps the dependency comparison trivial.
SSR-safe by construction, so don't guard it. No typeof window checks, no useEffect wrapper, no dynamic import. On the server the hook does nothing at all.

When Not to Use It

useEventListener is a primitive. If a purpose-built hook exists, it will handle the state, the edge cases and the cleanup you'd otherwise re-derive:

A click landing outside an element → useClickOutside or useClickAway (they handle the "mousedown started inside, mouseup outside" case you'd get wrong).
Hover, long-press, double-click, drag → useHover, useLongPress, useDoubleClick, useDraggable.
Element size or visibility → useResizeObserver, useElementSize, useIntersectionObserver. These are observers, not events; a resize listener on window cannot tell you an element changed size.
The event has a JSX prop and the target is your own element → just use onClick. Delegated React handlers are cheaper and colocated. Reach for a real listener when you need window/document, a non-passive listener, or an event React doesn't surface.
You only wanted a stable function identity → that's useEvent; no listener involved.

Takeaways

The useEffect + addEventListener pair forces a false choice: put the handler in the deps and re-subscribe on every render, or leave it out and call a stale closure.
useEventListener resolves it by registering a stable wrapper once and forwarding to a useLatest ref, so inline arrow handlers are free and addEventListener runs once per target.
Options are deep-compared, so an inline { passive: true } doesn't retrigger; the target is resolved at commit time, so refs work; the whole hook is a no-op during SSR.
TypeScript infers the exact event type for window and raw-element targets, and falls back to any for ref and function targets — annotate the handler parameter there, and watch for event-name typos, which those overloads won't catch.
Use it as a primitive to build your own hooks on. If a dedicated hook already exists for what you're listening to, use that instead.

useEventListener, useLatest, useClickOutside, and 110+ other SSR-safe, TypeScript-first hooks live in @reactuses/core — one install, tree-shakeable, no dependencies to babysit.

npm install @reactuses/core

React useScrollLock Hook: Lock Body Scroll for Modals (2026)

ReactUse — Wed, 19 Aug 2026 09:04:23 +0000

Your modal is open, centered, perfect. Then someone flicks the overlay and the page behind it scrolls away underneath. Everyone's first fix is the same three lines:

useEffect(() => {
  document.body.style.overflow = open ? "hidden" : "";
}, [open]);

It works on your laptop. Then the bug reports arrive:

On iPhone the page still moves. iOS Safari rubber-band scrolls the document by touch even with overflow: hidden on <body>.
Something else got wiped. "" isn't necessarily what was there before — you just erased whatever your design system or CSS-in-JS had set inline.
Two overlays, one frozen page. A drawer and a lightbox both own body.style.overflow; close them in the wrong order and the page never scrolls again.
The layout jumps the instant the desktop scrollbar disappears.

useScrollLock from @reactuses/core is those three lines with the hard parts handled: it restores the exact inline overflow it replaced, adds a touchmove guard on iOS that still lets your modal's own content scroll, exposes the lock as React state you can render off, and works on any element — not just <body>. This post covers what it actually does line by line, why overflow: hidden is not enough on iOS, how it compares to the position: fixed and body:has(dialog[open]) approaches, and the six gotchas that show up in real apps.

Quick Start

npm install @reactuses/core

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

function Modal({ open, onClose, children }: ModalProps) {
  // a getter, not `document.body` — see the SSR gotcha below
  const [, setLocked] = useScrollLock(() => document.body);

  useEffect(() => {
    setLocked(open);
    return () => setLocked(false); // release even if we unmount while open
  }, [open, setLocked]);

  if (!open) return null;

  return (
    <div className="overlay" onClick={onClose}>
      <div className="sheet" onClick={e => e.stopPropagation()}>
        {children}
      </div>
    </div>
  );
}

The signature:

const [locked, setLocked] = useScrollLock(target, initialState?)

target — the element whose scrolling you're locking. Accepts an element, a RefObject, or a getter () => element. Resolved lazily, on every call.
initialState — start locked. Defaults to false, and you should keep it that way (gotcha 3).
Returns [locked, setLocked]. locked is real state; setLocked is identity-stable, so it's safe in a dependency array or as a prop.

What useScrollLock Actually Does

The core of it, condensed from the source:

const [locked, setLocked] = useState(initialState);
const initialOverflowRef = useRef<CSSStyleDeclaration["overflow"]>("scroll");

useEffect(() => {
  const element = getTargetElement(target);
  if (element) {
    initialOverflowRef.current = element.style.overflow; // remember what we're replacing
    if (locked) element.style.overflow = "hidden";
  }
}, [locked, target]);

const lock = useEvent(() => {
  const element = getTargetElement(target);
  if (!element || locked) return;
  if (isIOS) element.addEventListener("touchmove", preventDefault, { passive: false });
  setLocked(true);
});

const unlock = useEvent(() => {
  const element = getTargetElement(target);
  if (!element || !locked) return;
  if (isIOS) element.removeEventListener("touchmove", preventDefault);
  element.style.overflow = initialOverflowRef.current; // restore, don't clobber
  setLocked(false);
});

Four decisions in there are worth naming, because they're exactly where hand-rolled versions differ:

The lock is state, not a fire-and-forget side effect. locked is a real useState value, so the same boolean that drives the style can drive your aria-hidden, your class names, your Esc handler.
It restores the inline value it replaced, not "". If something had set overflow: overlay inline, that's what comes back.
The target is resolved lazily through getTargetElement, which returns undefined when there is no window. Nothing touches the DOM on the server.
Only iOS gets a touchmove guard. Which is the genuinely interesting part.

Why `overflow: hidden` Isn't Enough on iOS

overflow: hidden on the scrolling element is the correct, spec-blessed way to stop scrolling — and iOS Safari has never fully honored it on <body>. Touch drags still rubber-band the document. The only reliable stop is to cancel the gesture itself:

element.addEventListener("touchmove", preventDefault, { passive: false });

passive: false is mandatory here, not decoration. Browsers register touch listeners on document-level targets as passive by default, and a passive listener's preventDefault() is ignored with a console warning — your lock would silently do nothing.

But a blanket preventDefault on touchmove breaks the thing you actually wanted: scrolling inside the modal. So the handler asks a question before cancelling:

function checkOverflowScroll(ele: Element): boolean {
  const style = window.getComputedStyle(ele);
  if (
    style.overflowX === "scroll" || style.overflowY === "scroll"
    || (style.overflowX === "auto" && ele.clientWidth < ele.scrollWidth)
    || (style.overflowY === "auto" && ele.clientHeight < ele.scrollHeight)
  ) return true;

  const parent = ele.parentNode as Element;
  if (!parent || parent.tagName === "BODY") return false;
  return checkOverflowScroll(parent);
}

Walk up from event.target; if any ancestor is genuinely scrollable — overflow: scroll, or overflow: auto with content that actually overflows right now — let the gesture through untouched. Otherwise cancel it. Two nice properties fall out of that:

An overflow: auto container whose content currently fits is not scrollable, so it gets locked — correctly. Add enough content and it starts scrolling again with no code change.
Multi-touch is excluded (if (e.touches.length > 1) return true, before any preventDefault), so pinch-to-zoom keeps working. Killing zoom inside a modal is an accessibility regression, and this sidesteps it.

useScrollLock vs the Other Four Approaches

Approach	Stops iOS rubber-band	Keeps inner scroll	Keeps scroll position	Cost
`body.style.overflow = "hidden"` by hand	❌	✅	✅	clobbers the inline style, never restores it
`body:has(dialog[open]) { overflow: hidden }`	❌	✅	✅	zero JS — but the same iOS hole
`body { position: fixed; top: -scrollY }`	✅	✅	only if you save and restore it yourself	takes `<body>` out of flow: `position: fixed` children re-anchor, scroll anchoring and `scroll-behavior: smooth` get strange
`overscroll-behavior: contain` on the dialog and `::backdrop`	✅ (Chrome 144+)	✅	✅	cleanest of all, where it's supported — and only for `<dialog>`
`useScrollLock`	✅	✅	✅	~40 lines of JS behind one hook call

One thing that trips people up: <dialog>.showModal() makes the rest of the document inert — clicks and Tab can't reach it — but it does not reliably block scrolling, particularly by touch on mobile. Inertness and scroll-locking are separate problems, and the browser only solves the first one for you.

And a complement rather than an alternative: overscroll-behavior: contain on your inner scroller stops scroll chaining — the inner list hitting its end and handing the gesture to the page. That's worth adding regardless of how you lock, but on its own it doesn't stop a drag that started on the backdrop.

Patterns

1. Declare the lock, don't toggle it

The Quick Start example is the pattern to internalize. Instead of calling setLocked(true) in your open handler and setLocked(false) in your close handler — two places to forget, plus every early-return path in between — bind the lock to the state that already describes the modal:

useEffect(() => {
  setLocked(open);
  return () => setLocked(false);
}, [open, setLocked]);

Now the lock can't drift out of sync with the UI, and the cleanup covers the case the imperative version always misses: a route change that unmounts the modal while it's open.

Combined with useDisclosure for the open/close state itself:

import { useDisclosure, useScrollLock } from "@reactuses/core";
import { useEffect } from "react";

function Drawer({ children }: { children: React.ReactNode }) {
  const { isOpen, onOpen, onClose } = useDisclosure();
  const [locked, setLocked] = useScrollLock(() => document.body);

  useEffect(() => {
    setLocked(isOpen);
    return () => setLocked(false);
  }, [isOpen, setLocked]);

  return (
    <>
      <button onClick={onOpen}>Menu</button>
      <main aria-hidden={locked}>{/* page content */}</main>
      {isOpen && (
        <aside className="drawer">
          {children}
          <button onClick={onClose}>Close</button>
        </aside>
      )}
    </>
  );
}

Note the locked half of the tuple earning its keep: one boolean drives both the style and the accessibility state, so they cannot disagree. (On React 19 you can use the same value for inert.)

2. Lock a scroll container, not the document

Plenty of apps don't scroll the document at all — the shell is height: 100vh; overflow: auto and everything scrolls inside a div. overflow: hidden on <body> does exactly nothing there, which is a confusing afternoon if you don't know it. Point the hook at the real scroller:

function Shell({ children }: { children: React.ReactNode }) {
  const scroller = useRef<HTMLDivElement>(null);
  const [, setLocked] = useScrollLock(scroller);

  return (
    <div ref={scroller} style={{ height: "100vh", overflow: "auto" }}>
      {children}
    </div>
  );
}

Same hook, same tuple. This is why target is required rather than defaulting to document.body: the library can't know which element is your scroll root.

3. Lock during a drag

Touch-dragging a slider, a sortable list, or a custom carousel scrolls the page unless something stops it — and a touchmove guard is exactly the right tool:

const [, setLocked] = useScrollLock(() => document.body);

<div
  onPointerDown={() => setLocked(true)}
  onPointerUp={() => setLocked(false)}
  onPointerCancel={() => setLocked(false)}
/>

onPointerCancel matters: the browser can steal the pointer mid-gesture, and without it you'd leave the page locked. If you're building the drag itself rather than wiring one up, useDraggable already handles the pointer bookkeeping.

Gotchas Worth Knowing

1. The lock is a style, not a lifecycle

The lock is an inline overflow: hidden written onto an element the hook doesn't own, so something has to put it back. Since @reactuses/core v6.5.3 the hook does that itself when the owning component unmounts: it restores the exact inline value it replaced and detaches the iOS touchmove guard, so a route change with the modal still open can no longer leave the page frozen. On v6.5.2 and earlier it didn't — worth knowing if you're pinned to an older version, because on iOS the leftover passive: false listener kills touch scrolling for the rest of the session, not just the style.

Unmounting is only half of it. The other half — the modal closing while the component stays mounted — is yours either way, which is exactly why the pattern above binds setLocked to open with a cleanup instead of toggling it from two handlers:

useEffect(() => {
  setLocked(open);
  return () => setLocked(false);
}, [open, setLocked]);

Think of the setter as owning a style you borrowed. Every borrow needs a return.

2. One owner per element

Two hook instances locking the same element is the subtlest failure mode, because each keeps its own memory of the original overflow:

A.lock()    → overflow: hidden    (A remembered "auto")
B.lock()    → overflow: hidden    (B remembered "hidden" 😬)
A.unlock()  → overflow: auto      (page scrolls, though B still thinks it's locked)
B.unlock()  → overflow: hidden    (page is now stuck, with nothing open)

Nothing is going to save you here — this is inherent to "save the old value, put it back" and applies to every hand-rolled lock and most libraries. The answer is architectural: one lock owner per element. Put the useScrollLock(() => document.body) call in your layout, provider, or store, and let modals ask it to lock rather than each carrying its own.

3. `initialState: true` skips the iOS guard

useScrollLock(target, true) applies overflow: hidden from the first commit — but the touchmove listener is only attached inside lock(), which never ran. So a page that starts locked is still rubber-band-scrollable on iOS. Start false and flip it:

const [, setLocked] = useScrollLock(() => document.body);
useEffect(() => { setLocked(true); }, [setLocked]); // locked from mount, guard included

4. Desktop layout shift

Hiding the scrollbar reclaims ~15px and the entire page shifts sideways. That's not the hook's job to fix, and it's one CSS line:

html { scrollbar-gutter: stable; }

5. Pass a getter, not `document.body`, for SSR

useScrollLock(document.body) evaluates document.body during render, which throws on the server before the hook gets a chance to be careful. () => document.body (or a ref) is only read inside effects and handlers, where getTargetElement already bails out without a window:

const [, setLocked] = useScrollLock(() => document.body); // ✅ SSR-safe
const [, setLocked] = useScrollLock(document.body);       // ❌ crashes on the server

The same rule applies to every hook in the library that takes an element target, and it's the single most common SSR mistake in Next.js and Remix apps.

6. `hidden` stops gestures, not programmatic scrolling

An overflow: hidden box is still scrollable via scrollTop, scrollTo, scrollIntoView — and, crucially, by the browser scrolling a newly focused element into view. If focus escapes to a link behind your modal, your "locked" page will scroll to it. Scroll locking and focus trapping are two halves of the same feature; ship both.

When Not to Use useScrollLock

You only need to stop an inner scroller from chaining to the page → overscroll-behavior: contain in CSS, no JavaScript at all.
You're using <dialog> and can require Chrome 144+ → overscroll-behavior: contain on the dialog and its ::backdrop is less code than any hook.
You want to scroll to something → useScrollIntoView, or the native one-liner — yesterday's post on scrollIntoView with useRef covers both.
You want to read or react to scroll position → useScroll or useWindowScroll.
You want a genuinely immersive, chrome-free view → useFullscreen instead of locking a scroll container.
You're loading more rows as the user scrolls → useInfiniteScroll; the last thing you want there is a lock.

Takeaways

overflow: hidden is the right mechanism on desktop and an incomplete one on iOS Safari, where only cancelling touchmove (with passive: false) actually stops the document from rubber-banding.
useScrollLock pairs that guard with a scroll-aware ancestor check, so the page can't move while your modal's own content still scrolls — and multi-touch zoom survives.
It restores the exact inline overflow it replaced, exposes the lock as state you can render off, and works on any element, which is what you need when your app scrolls inside a div rather than the document.
Bind the lock to the state that describes your UI (setLocked(open) plus a cleanup), keep one owner per element, start initialState at false, pass a getter for SSR, and add scrollbar-gutter: stable for the desktop shift.
Scroll locking is half a modal. Trap focus too, or hidden will still scroll when something behind the overlay takes focus.

useScrollLock, useDisclosure, useScrollIntoView, and 110+ other SSR-safe, TypeScript-first hooks live in @reactuses/core — one install, tree-shakeable, no dependencies to babysit.

npm install @reactuses/core

React scrollIntoView with useRef: Scroll to an Element (2026)

ReactUse — Tue, 18 Aug 2026 01:54:50 +0000

You have a long form. The user hits Submit, validation fails on a field three screens down, and the error message renders somewhere they can't see. The fix is one browser API call — but where you put it, and what you pass it, is where an afternoon goes.

The short answer, which is what most people are here for:

import { useRef } from "react";

function Article() {
  const sectionRef = useRef<HTMLDivElement>(null);

  return (
    <>
      <button onClick={() => sectionRef.current?.scrollIntoView({ behavior: "smooth" })}>
        Jump to details
      </button>
      {/* … a lot of content … */}
      <div ref={sectionRef}>Details</div>
    </>
  );
}

That's the whole pattern: a ref on the element, .scrollIntoView() in the handler, ?. because sectionRef.current is null until React commits. It's built into every browser, it costs nothing, and for a static anchor like this it's the right answer — don't reach for a library.

This post covers the rest of it: what the arguments actually do, the sticky-header offset problem (and why the CSS answer beats the JavaScript one), how to scroll to something that was just rendered, and the four things the native call genuinely can't do — at which point useScrollIntoView from @reactuses/core earns its place.

The Arguments You Actually Have

Element.scrollIntoView() takes one optional options object with three keys:

Option	Values	Default	What it does
`block`	`start` · `center` · `end` · `nearest`	`start`	Alignment along the block axis — vertical in a normal writing mode
`inline`	`start` · `center` · `end` · `nearest`	`nearest`	Alignment along the inline axis — horizontal
`behavior`	`auto` · `instant` · `smooth`	`auto`	`auto` follows the CSS `scroll-behavior` of the scrolling box

So the three calls worth memorizing:

el.scrollIntoView();                                        // snap it to the top
el.scrollIntoView({ behavior: "smooth", block: "center" }); // glide it to the middle
el.scrollIntoView({ block: "nearest" });                    // move only if it's off-screen

block: "nearest" is the underrated one. It scrolls the minimum distance needed to bring the element into view and does nothing at all if the element is already visible — exactly what you want for keyboard navigation in a listbox, where re-centering on every arrow key makes the list feel like it's fighting you.

There's also a legacy boolean form: scrollIntoView(true) means block: "start", scrollIntoView(false) means block: "end". It still works everywhere; the object form says what it means.

One thing that surprises people: scrollIntoView scrolls every scrollable ancestor, not just the nearest one. If your element sits in a scrollable panel inside a scrollable page, both move so the element ends up visible. That's almost always what you wanted.

Sticky Headers: Use CSS, Not a Magic Number

The single most common follow-up: you scroll to a heading, and your 64px sticky header sits right on top of it.

The instinct is to compute it by hand:

// don't
const top = el.getBoundingClientRect().top + window.scrollY - 64;
window.scrollTo({ top, behavior: "smooth" });

Now you own that 64. It's wrong on mobile where the header is shorter, wrong when a promo banner appears above it, wrong when the element is inside a scroll container rather than the page, and you've given up scrollIntoView's ancestor handling to boot.

The platform has a property for exactly this:

.section {
  scroll-margin-top: 5rem; /* or var(--header-height) */
}

scroll-margin-top tells the browser to treat the element as if it had that much extra margin for scrolling purposes only. Plain el.scrollIntoView({ behavior: "smooth" }) then stops 5rem short, layout is untouched, and the value lives next to the header height it depends on. It also fixes :target anchors and browser find-in-page for free, which the JavaScript version never will.

Reach for scroll-margin-top first. Every time.

Scrolling to Something That Just Rendered

The other half of the problem is timing. You add an item to a list and want to scroll to it; you open an accordion and want to reveal it; you set an error and want to jump to it. The naive version doesn't work:

// broken: the DOM doesn't have the new row yet
function addRow() {
  setRows(r => [...r, newRow]);
  lastRowRef.current?.scrollIntoView(); // still the *old* last row, or null
}

setRows schedules a render. React commits it later — and under React 18+ concurrent rendering, "later" is genuinely not this tick. At the moment that line runs, the DOM is still the old DOM.

The default fix is an effect. Scroll after the commit that added the row:

useEffect(() => {
  lastRowRef.current?.scrollIntoView({ behavior: "smooth", block: "nearest" });
}, [rows.length]);

Use useLayoutEffect instead if you want an instant scroll to land before the browser paints — otherwise the user sees one frame at the old position, which reads as a flicker. For a smooth scroll it doesn't matter; the animation starts either way.

Callback refs are cleaner for "the element I just created". No effect, no dependency array, no ref to keep in sync — the callback fires the moment React attaches the node:

const scrollOnMount = useCallback((node: HTMLElement | null) => {
  node?.scrollIntoView({ behavior: "smooth", block: "nearest" });
}, []);

// …
{rows.map((row, i) => (
  <Row key={row.id} ref={i === rows.length - 1 ? scrollOnMount : undefined} />
))}

flushSync is the escape hatch, not the default. If you truly must scroll in the same event handler that changed the state, you can force the commit:

import { flushSync } from "react-dom";

flushSync(() => setExpanded(true));
detailsRef.current?.scrollIntoView({ behavior: "smooth" });

It works, and it costs you the batching and concurrency React was doing on your behalf. Fine as a one-off in a handler; a smell if it shows up three times in a file.

Where the Native Call Runs Out

For anchors, "scroll to the error", and keyboard list navigation, everything above is enough and you should stop reading. Four things it genuinely cannot do:

1. You can't control the duration or the curve. behavior: "smooth" is whatever the browser decides — different speed in Chrome and Firefox, and no knob at all. If the scroll is part of a choreographed transition that has to line up with a 400ms fade, you can't.

2. There's no reliable "it finished" callback. The scrollend event was designed for this and landed in Chrome/Edge 114 and Firefox 109, with Safari following later — check support before you depend on it, and note it doesn't tell you which programmatic scroll ended. The workarounds people ship instead (a setTimeout guess, polling scrollY until it stops changing) are exactly as fragile as they sound.

3. You can't cancel it. Start a long smooth scroll, and if the user grabs the wheel halfway down, the browser keeps dragging them to the destination. On a long page this is the single most annoying scroll bug there is, and there is no API to stop it.

4. It ignores prefers-reduced-motion. Browsers do not universally downgrade behavior: "smooth" for users who asked for reduced motion — that's on you:

const reduce = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
el.scrollIntoView({ behavior: reduce ? "auto" : "smooth" });

Easy to write once, easy to forget in the other eleven places you scroll.

useScrollIntoView

useScrollIntoView runs the animation itself on requestAnimationFrame, which is what buys back all four:

npm install @reactuses/core

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

function Article() {
  const targetRef = useRef<HTMLParagraphElement>(null);
  const { scrollIntoView, cancel } = useScrollIntoView(targetRef, {
    duration: 600,
    offset: 80,
    onScrollFinish: () => targetRef.current?.focus(),
  });

  return (
    <>
      <button onClick={() => scrollIntoView({ alignment: "center" })}>Jump to details</button>
      <div style={{ height: "150vh" }} />
      <p ref={targetRef} tabIndex={-1}>Details</p>
    </>
  );
}

useScrollIntoView(target, options?, scrollContainer?) returns { scrollIntoView, cancel }. It's SSR-safe — nothing touches the DOM until you call it — and the target can be a ref, an element, or a getter function, so it works with whatever you already have.

The options, all optional:

Option	Default	Notes
`duration`	`1250`	Milliseconds. `0` jumps instantly.
`easing`	`easeInOutQuad`	Any `(t: number) => number` over `0…1`.
`axis`	`"y"`	`"x"` for horizontal scrollers. One axis per hook.
`offset`	`0`	Extra distance from the edge — the sticky-header allowance.
`cancelable`	`true`	Wheel or touch input aborts the animation.
`isList`	`false`	Skip the scroll when the target is already in view.
`onScrollFinish`	—	Fires when the animation settles.

And the alignment goes on the call, not the config, because it's usually per-invocation: scrollIntoView({ alignment: "start" | "center" | "end" }).

Cancelable is the one you'll actually feel

With cancelable: true (the default) the hook watches for wheel and touchmove and stops the animation where it is. The user reaches for the scrollbar mid-flight and the page just… lets them. Compare that with behavior: "smooth", which will happily fight a user for a full second.

You can also stop it yourself — closing the modal that triggered the scroll, say:

const { scrollIntoView, cancel } = useScrollIntoView(targetRef);
useEffect(() => cancel, [cancel]); // it also cancels on unmount

Reduced motion is handled

The hook reads prefers-reduced-motion internally via useReducedMotion. When the user has asked for less motion, the easing collapses to its final value and the scroll becomes an instant jump — same destination, same onScrollFinish, no animation. You don't write the branch.

Scrolling inside a container, and sideways

Pass a scroll container as the third argument when you want to move a specific element's scroll position rather than the page:

const listRef = useRef<HTMLDivElement>(null);
const itemRef = useRef<HTMLLIElement>(null);

const { scrollIntoView } = useScrollIntoView(itemRef, { isList: true }, listRef);

Without the third argument the hook walks up from the target and picks the first ancestor whose computed overflow-x/overflow-y is auto or scroll, falling back to the page. That auto-detection is convenient and correct most of the time; pass the container explicitly when you know it.

For a carousel, flip the axis:

const { scrollIntoView } = useScrollIntoView(slideRef, { axis: "x", duration: 400 }, trackRef);
scrollIntoView({ alignment: "center" });

Scroll to the first invalid field

The pattern that started this post, with the pieces in the right places:

function CheckoutForm() {
  const [errors, setErrors] = useState<Record<string, string>>({});
  const firstErrorRef = useRef<HTMLDivElement>(null);

  const { scrollIntoView } = useScrollIntoView(firstErrorRef, {
    offset: 96,          // clear the sticky header
    duration: 500,
    onScrollFinish: () => firstErrorRef.current?.querySelector("input")?.focus(),
  });

  function onSubmit(e: React.FormEvent) {
    e.preventDefault();
    const next = validate(values);
    setErrors(next);
    if (Object.keys(next).length > 0) scrollIntoView({ alignment: "start" });
  }

  const firstErrorField = Object.keys(errors)[0];

  return (
    <form onSubmit={onSubmit}>
      {FIELDS.map(f => (
        <Field key={f.name} ref={f.name === firstErrorField ? firstErrorRef : undefined} {...f} />
      ))}
    </form>
  );
}

Because the hook resolves the target when you call scrollIntoView — not when it renders — calling it in the same handler as setErrors works even though firstErrorRef is attached by the render that setErrors triggers. No flushSync, no effect. Moving focus in onScrollFinish rather than immediately means screen-reader users and sighted users arrive at the same time.

Gotchas Worth Knowing

offset doesn't apply to alignment: "center". It's an allowance measured from the nearest edge, so it only affects "start" and "end". Centering something under a sticky header means either using "start" with an offset, or accepting the center. This one silently does nothing if you assume otherwise.
Don't combine it with scroll-behavior: smooth. The hook animates by assigning scrollTop/scrollLeft every frame. If CSS also says that box scrolls smoothly, the browser tries to animate each of those ~60 assignments and the result is a stuttering mess. Pick one: CSS smooth scrolling or this hook, per container.
One axis per hook. axis is "x" or "y", not both. A grid that needs diagonal movement needs two hooks, or the native call.
The auto-detected scroll parent is cached per element. The first lookup for a given node is remembered. If your layout toggles overflow on an ancestor at runtime — a panel that becomes scrollable only when expanded — pass the container as the third argument instead of relying on detection.
cancelable covers wheel and touch, not keys. Page Down and the scrollbar don't abort the animation. It's the common case, not every case; call cancel() yourself from a keydown handler if that matters to you.
isList is directional. With isList: true the hook only moves when the target is outside the container on the side implied by alignment — a target already visible produces no scroll at all. That's the point (it stops a keyboard-navigated list from jittering on every keystroke), but it means isList: true with the wrong alignment can look like the hook is ignoring you.
duration: 0 is an instant jump, not a no-op. Useful for honouring your own "no animations" setting without branching on which function to call.

When to Skip the Hook

Native scrollIntoView is the right call more often than not:

A static anchor or a table-of-contents link → el.scrollIntoView({ behavior: "smooth" }) plus scroll-margin-top. No dependency, no animation loop.
Keyboard navigation in a listbox → block: "nearest" does the minimum-movement behaviour natively, and instant is the correct feel there anyway.
You need to align on both axes at once → the native call takes block and inline.
You're scrolling to a position, not an element → window.scrollTo / el.scrollTo, or useScroll to read and react to scroll position.
You want to know what's on screen rather than move to it → useIntersectionObserver, which is also how you highlight the current section in a TOC.
You want to stop the page scrolling entirely (modal open) → useScrollLock.

Takeaways

The baseline is three lines: useRef on the element, ref.current?.scrollIntoView({ behavior: "smooth" }) in the handler, ?. because the ref is null before commit. Learn block: "nearest" — it's the one you'll use most.
Solve sticky-header overlap with scroll-margin-top in CSS, not by subtracting a hard-coded pixel value from getBoundingClientRect(). It survives responsive headers and fixes :target anchors too.
To scroll to something you just rendered, scroll in an effect keyed on the change, or use a callback ref. flushSync works but gives up batching — keep it as an escape hatch.
Native smooth scrolling has no duration control, no dependable completion event, no cancel, and no prefers-reduced-motion handling. If none of those matter, don't add a dependency.
useScrollIntoView covers exactly those gaps — configurable duration/easing, onScrollFinish, wheel-and-touch cancellation, automatic reduced-motion fallback, plus offset, horizontal axis, an explicit scroll container, and isList for jitter-free list navigation. It resolves the target at call time, so it works in the same handler as the setState that rendered it.

useScrollIntoView, useScroll, useScrollLock, and 110+ other SSR-safe, TypeScript-first hooks live in @reactuses/core — one install, tree-shakeable, no dependencies to babysit.

npm install @reactuses/core

React useSessionStorage Hook: Per-Tab State That Survives Reloads (2026)

ReactUse — Mon, 17 Aug 2026 02:35:15 +0000

Here's a checkout flow that loses the customer at step three:

function Checkout() {
  const [step, setStep] = useState(0);
  const [form, setForm] = useState<CheckoutForm>(EMPTY_FORM);
  // step 1: address, step 2: shipping, step 3: payment…
}

The customer fills in their address, picks a shipping option, and on the payment step the provider redirects them out to a 3-D Secure page and back. Or they just hit refresh. Either way, step is 0 again and form is empty. useState lives exactly as long as the component instance does — a reload, a redirect, a full-page navigation, and it's gone.

Everyone knows the fix is Web Storage. Most people reach for localStorage, and it works — until it works too well. The half-finished checkout is now sitting in every tab the customer opens, it's still there next week when they come back for something else, and if they open two tabs to compare shipping options, useLocalStorage faithfully syncs the two forms into each other. What you actually wanted was state that survives this tab's reloads and redirects and then disappears when the tab does. That's sessionStorage, and useSessionStorage from @reactuses/core is the useState-shaped hook for it. This post covers what sessionStorage really promises (and doesn't), when to choose it over localStorage and cookies, the four patterns it's built for, and the gotchas — hydration, tab restore, window.open — that bite the hand-rolled version.

Quick Start

npm install @reactuses/core

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

function Checkout() {
  const [step, setStep] = useSessionStorage("checkout:step", 0);
  const [form, setForm] = useSessionStorage<CheckoutForm>("checkout:form", EMPTY_FORM);

  return (
    <Wizard step={step ?? 0} onNext={() => setStep(s => (s ?? 0) + 1)}>
      <AddressStep value={form!.address} onChange={address => setForm(f => ({ ...f!, address }))} />
      {/* … */}
    </Wizard>
  );
}

useSessionStorage(key, defaultValue) returns the same [value, setValue] tuple as useState, with the same functional updates. The value is read from sessionStorage on mount, written back on every update, and typed T | null — null because setValue(null) removes the key (more on that below). Reload the page, get redirected to a payment provider and back, navigate away and hit the browser's back button: step and form are exactly where the customer left them. Close the tab: they're gone, which is the point.

What sessionStorage Actually Promises

The name misleads people into thinking "session" means "logged-in session" or "browser session". It means one top-level browsing context — a tab or window — for one origin. Concretely:

Event	Survives?
Reload / hard refresh	✅
Client-side route change (SPA)	✅
Full-page navigation to another page on the same origin	✅
Redirect to a third-party site and back (OAuth, payment, SSO)	✅ — same tab, same origin on return
Browser back / forward	✅
Open the same URL in a new tab	❌ fresh, empty storage
Close the tab	❌ cleared (with a caveat: browsers that restore closed tabs restore its `sessionStorage` too)
Close the browser	❌

Two edge cases surprise people. First, window.open() copies the opener's sessionStorage into the new window (per the HTML spec, whenever the new window keeps an opener), and Chrome's "Duplicate tab" copies it too — but it's a one-time snapshot, not a live link; the two tabs diverge from then on. Modern browsers open target="_blank" links with noopener by default, so ordinary links start clean. Second, sessionStorage is shared with same-origin iframes in the same tab — they're the same browsing context group — which is the only place the browser's native storage event has any meaning for it (below).

The rest is the same contract as localStorage: synchronous, string-only, roughly 5 MB per origin, and readable by any script on the page — so it's not a security boundary. It's shorter-lived than localStorage, which limits the blast radius of a leak, but XSS reads it just as easily. Anything that must be secret from JavaScript belongs in an httpOnly cookie, not here.

useSessionStorage vs useLocalStorage vs useCookie vs useState

Pick by where the value should live and how long:

You need state that…	Reach for
lives as long as the component	`useState`
survives reloads and redirects in this tab, then disappears	`useSessionStorage`
survives browser restarts and stays in sync across tabs	`useLocalStorage`
the server needs on the first request	`useCookie`
is messaged between tabs, not stored	`useBroadcastChannel`

The rule of thumb that resolves 90% of "local or session?" debates: if two tabs showing different values would be a bug, use localStorage; if two tabs showing the same value would be a bug, use sessionStorage. Theme, language, "don't show this again forever" — a user expects those to be one value everywhere, so local. A half-completed form, the filters on this dashboard view, the page you were on before an auth redirect — those belong to one tab, so session.

useSessionStorage and useLocalStorage share the exact same API, serialization, and internals — swap the import and the lifetime changes, nothing else does. Everything in the useLocalStorage deep-dive about hydration, setValue(null), custom serializers and onError applies verbatim, so I'll only recap the parts that matter and spend the rest on the session-specific patterns and gotchas.

What You Get Over the Hand-Rolled Version

Every codebase has a useState initializer that reads storage plus a useEffect that writes it back. Here's what that version gets wrong and useSessionStorage gets right:

SSR and hydration. The hook is built on useSyncExternalStore with a server snapshot that returns the default. It never touches window on the server, and the client's first render matches the server HTML, then re-renders with the stored value through the proper path — no crash, no hydration-mismatch warning, no typeof window guard in your code.
Serialization by default type. Pass a number and you get a number back; pass an object and it's JSON.stringify/JSON.parse; pass a Map, Set or Date and they round-trip correctly (a plain JSON.stringify(new Map()) gives you {}). Need a specific wire format? Provide serializer: { read, write }.
setValue(null) removes the key. "Cleared" is a real state, distinct from "reset to default": after setForm(null) the value is null, and on the next mount it comes back as EMPTY_FORM. That's your "start over" button, and it's why the type is T | null.
Corrupted data doesn't crash. Someone edits DevTools, an old deploy wrote a different shape, a JSON.parse throws — the hook returns the default and reports through onError (default console.error) instead of taking the component down.
Storage unavailable? Degrades to memory. Some privacy modes and embedded contexts throw on storage access. The hook catches it, calls onError, and behaves like plain useState for the rest of the session.
Every component on the same key agrees. Two useSessionStorage("checkout:step", 0) calls — a progress bar in the header, the wizard body — re-render together on every write. The native storage event never fires in the document that made the change, so the hand-rolled version drifts; the hook re-broadcasts each write internally so it can't.

Patterns

Multi-step forms and wizards

The intro's checkout, done properly. Two details worth copying: namespace your keys (checkout:step, checkout:form) so a "start over" can clear them together and unrelated features on the same origin never collide, and store the draft separately from what's been submitted, so a successful order can wipe the draft without touching anything else:

const [step, setStep] = useSessionStorage("checkout:step", 0);
const [draft, setDraft] = useSessionStorage<CheckoutForm>("checkout:form", EMPTY_FORM);

async function submit() {
  await api.placeOrder(draft!);
  setDraft(null); // remove the key — nothing lingers in the tab
  setStep(null);
  navigate("/thank-you");
}

For a large form with a keystroke-per-field update rate, storage writes are synchronous but cheap (a few KB of JSON); if you'd rather batch them, wrap the field updates in useDebounceFn and write the draft on the trailing edge.

Surviving a redirect round-trip

OAuth, SSO, payment providers, "verify your email" links that come back to the app — anything that navigates the tab away and returns needs to stash "where was I?" somewhere that survives a full-page unload but shouldn't be shared with the tab next door. That's sessionStorage's home turf: it's where auth libraries like MSAL keep their PKCE verifier and state by default, for exactly this reason.

function useReturnTo() {
  const [returnTo, setReturnTo] = useSessionStorage<string>("auth:returnTo", null);
  const navigate = useNavigate();

  const stashAndRedirect = () => {
    setReturnTo(window.location.pathname + window.location.search);
    window.location.assign(buildAuthorizeUrl());
  };

  const restore = () => {
    const target = returnTo ?? "/";
    setReturnTo(null); // consume it — one round-trip, one restore
    navigate(target, { replace: true });
  };

  return { stashAndRedirect, restore };
}

Two tabs, two logins, two different returnTos — no cross-talk. Had this been localStorage, tab B's redirect would overwrite tab A's return path.

Per-tab view state that must not sync

The case that catches useLocalStorage fans off guard: a user opens two tabs of the same dashboard to compare "last 7 days" against "last 30 days". With localStorage and cross-tab sync, changing the range in one tab changes it in the other, and the user is left thinking the app is haunted. Any view state that's about this window — filters, sort column, expanded rows, which side panel is open — is a sessionStorage value:

const [range, setRange] = useSessionStorage<"7d" | "30d" | "90d">("dashboard:range", "7d");

Reload preserves it, a second tab starts from the default, and the two never fight. If you also want a persisted "last used" default across sessions, keep that in localStorage and read it as the session default — two hooks, two lifetimes, both explicit.

Once per session

Announcement banners, "we use cookies" notices, an onboarding tooltip — things a user should be able to dismiss for the duration of their visit without you promising to hide them forever:

function ReleaseBanner() {
  const [dismissed, setDismissed] = useSessionStorage("banner:v6.5-dismissed", false);
  if (dismissed) return null;
  return (
    <aside>
      New in v6.5 — <a href="/changelog">see what changed</a>
      <button onClick={() => setDismissed(true)}>Dismiss</button>
    </aside>
  );
}

Ship it in the key (banner:v6.5-dismissed) so a new release gets a fresh banner without touching the old flag. The same shape works for "the user already saw the intro animation this session" — pair it with useReducedMotion if the animation is the kind you should skip anyway.

A stable per-tab ID

sessionStorage is the only browser primitive that naturally gives you "one value per tab that survives reloads". That's precisely what you want for a tab identifier — tagging analytics events, correlating logs, or telling useBroadcastChannel messages apart by sender. mountStorageValue seeds the key on first mount only if it's absent:

const [tabId] = useSessionStorage<string>("tab:id", null, {
  mountStorageValue: () => crypto.randomUUID(),
});
// null on the very first render, then a UUID that's stable across reloads of this tab

Gotchas Worth Knowing

The default flashes before the stored value, once. Under SSR the server can't see the browser's storage, so the first paint shows the default and the stored value arrives on the post-hydration render. For a wizard step that's a non-issue; for something like "which panel is open" you may want a skeleton until the value is in. The trade-offs are the same as for localStorage — see SSR-Safe React Hooks.
"Cleared when the tab closes" has an asterisk. Chrome, Firefox and Safari all restore sessionStorage when the user reopens a closed tab or the browser restores a session after a crash. Don't rely on tab close as a guaranteed wipe for anything sensitive; if it must go, setValue(null) it yourself.
New tab ≠ same tab. Users who Ctrl-click your link into a new tab arrive with empty sessionStorage. That's usually correct (they want a fresh view), but it means "the user has already dismissed the banner" and "the wizard is on step 3" don't carry over. If they should, that's a localStorage value.
window.open() copies, then forks. If you window.open() a same-origin popup (a preview, a print view), it starts with a copy of the opener's sessionStorage. Writes in the popup don't reach the opener; use useBroadcastChannel or postMessage if they need to.
listenToStorageChanges is mostly moot for sessionStorage. The native storage event only reaches other documents sharing the same area — for sessionStorage, that's same-origin iframes in the same tab, not other tabs. Same-tab sync between components is a separate, always-on mechanism and isn't affected by the option; leave it at the default and forget about it unless you have iframes.
Not a vault. It's JavaScript-readable storage. It's fine for a PKCE verifier (single-use, short-lived, and worthless without the authorization code) and for drafts and view state; it's the wrong place for a long-lived access token you'd be upset to see exfiltrated. Server-side sessions and httpOnly cookies exist for that.
Storage can be full or blocked. Quota is small and shared with everything else on the origin; some embedded/private contexts throw on access. Both are reported through onError and the hook keeps working in memory. Log it — a "my form reset" bug report often traces back to a QuotaExceededError nobody looked at.
The value is T | null, on purpose. After setValue(null) the key is gone and you get null, not the default. If your code can't handle null, either never call setValue(null) (write the default instead) or normalize at the read site: const s = step ?? 0.

When Not to Use useSessionStorage

The value should be one thing everywhere, forever (theme, locale, "never show again") → useLocalStorage.
The server needs it on the first request (theme without a flash, A/B bucket, auth session) → useCookie.
Tabs need to talk, not *store* ("you were logged out in another tab") → useBroadcastChannel.
You're keeping a value across renders, not across reloads → useState, useRef, or useLatest — the previous post in this series covers when each applies.
You want it in the URL (shareable filters, deep-linkable steps) → put it in the query string; that beats every storage API when a link should reproduce the view.

Takeaways

sessionStorage = one tab, one origin, until the tab closes. It survives reloads, SPA and full-page navigations, back/forward, and redirect round-trips; it does not cross into new tabs (except as a one-time copy via window.open() / duplicate-tab), and browsers may restore it when a closed tab is reopened.
useSessionStorage(key, default) is a drop-in useState with that lifetime: same tuple, functional updates, automatic serialization for objects/Maps/Sets/Dates, setValue(null) to remove, onError for corrupt data and blocked storage, SSR-safe via useSyncExternalStore, and every component on the same key stays in sync.
Rule of thumb: two tabs disagreeing would be a bug → localStorage; two tabs agreeing would be a bug → sessionStorage. Multi-step forms, redirect round-trips, per-tab view state, once-per-session flags, and per-tab IDs are session values.
It's a lifetime, not a security boundary. Keep secrets in httpOnly cookies, and clear sensitive keys yourself with setValue(null) rather than trusting tab close.

useSessionStorage, useLocalStorage, useCookie, and 110+ other SSR-safe, TypeScript-first hooks live in @reactuses/core — one install, tree-shakeable, no dependencies to babysit.

npm install @reactuses/core

React useLatest Hook: Read Fresh State in Async Callbacks (2026)

ReactUse — Sun, 16 Aug 2026 02:38:31 +0000

Here's an autosave button that lies to the user:

function Editor({ docId }: { docId: string }) {
  const [text, setText] = useState("");
  const [status, setStatus] = useState<"idle" | "saving" | "saved" | "dirty">("idle");

  async function save() {
    setStatus("saving");
    await api.save(docId, text);
    setStatus("saved"); // ⚠️ but the user kept typing during the await…
  }

  return (
    <>
      <textarea value={text} onChange={e => setText(e.target.value)} />
      <button onClick={save}>Save</button> <em>{status}</em>
    </>
  );
}

The request takes 800 ms. The user types three more words while it's in flight. The promise resolves, status flips to "saved", and the three new words are not saved. Inside save, text is whatever it was when the button was clicked — a JavaScript closure captured that render's value, and no amount of re-rendering will update it. To decide between "saved" and "dirty" after the await, you need to know what text is now, and the closure can't tell you.

That's the stale closure, and it shows up anywhere a callback outlives the render that created it: setTimeout, setInterval, code after an await, event listeners registered once, IntersectionObserver and ResizeObserver callbacks, WebSocket onmessage, and every third-party SDK that takes a callback at construction time. React's own FAQ answers "why am I seeing stale props or state inside my function?" with a ref that always holds the latest value. useLatest from @reactuses/core is that ref, packaged: five lines, no re-renders, no dependency arrays. This post covers what it is, why the implementation writes the ref in a layout effect rather than during render, how it relates to useRef, useEvent and React's useEffectEvent, the patterns it's built for, and the one rule you must respect.

Quick Start

npm install @reactuses/core

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

function Editor({ docId }: { docId: string }) {
  const [text, setText] = useState("");
  const [status, setStatus] = useState<"idle" | "saving" | "saved" | "dirty">("idle");
  const latestText = useLatest(text);

  async function save() {
    const snapshot = text; // the closure: what we're sending
    setStatus("saving");
    await api.save(docId, snapshot);
    // the ref: what the user has NOW
    setStatus(latestText.current === snapshot ? "saved" : "dirty");
  }

  // …
}

useLatest(value) returns a MutableRefObject<T> whose .current is always the most recently rendered value. The ref object itself never changes identity, so it's safe to close over anywhere — timers, promises, subscriptions — and read whenever the callback finally runs. Notice the fixed example uses both the closure and the ref: the closure is the value at the moment of the click (correct for "what did we send?"), the ref is the value at the moment the promise resolves (correct for "is it still current?"). Stale closures aren't a bug in JavaScript; they're only a bug when you wanted now and got then.

What useLatest Actually Is

The whole hook, from @reactuses/core:

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

function useLatest<T>(value: T) {
  const ref = useRef(value);
  useIsomorphicLayoutEffect(() => {
    ref.current = value;
  }, [value]);
  return ref;
}

That's it. A ref, created once, whose .current is overwritten every time value changes. Two details are worth understanding, because they're where hand-rolled versions differ.

Why a layout effect, and not ref.current = value in the render body? Several popular implementations (react-use, ahooks) assign during render, and it works almost all the time. But React's rules say render must be pure — no reads or writes to ref.current during rendering — because with concurrent rendering a render can be started, paused, and thrown away without ever committing. A ref written during a discarded render now holds a value that no committed UI ever showed. Writing in useLayoutEffect means the ref updates exactly once per committed render, synchronously after the DOM is updated and before the browser paints. That's the same trick the React useEvent RFC uses, and it's why @reactuses/core builds useEvent, useInterval, useTimeoutFn and a dozen other hooks on top of useLatest instead of a bare render-time assignment.

Why not a plain useEffect? Ordering. Passive effects run after paint, and in the same commit React runs children's effects before parents' and earlier hooks before later ones. If some other effect in the same commit reads the ref before the updating effect has run, it sees last render's value. Layout effects run before any passive effect, so by the time any useEffect, event handler, timer or promise callback fires, ref.current is current. (useIsomorphicLayoutEffect is just useLayoutEffect in the browser and useEffect on the server, so there's no SSR warning.)

The consequence you should internalize: .current reflects the last committed render, and it's meant to be read from callbacks, not from render. During the render of update N+1, ref.current still holds N's value — which is fine, because in render you should be reading value directly anyway. If you find yourself writing {latest.current} in JSX, you wanted plain state.

useLatest vs useRef vs useState

These three get confused because they all "hold a value". The question is who needs the value and when.

You need to…	Reach for
render the value, and re-render when it changes	`useState`
keep a mutable value across renders that isn't derived from a prop/state (a timer id, a DOM node, a counter)	`useRef`
read the latest prop or state from a callback that outlives the render	`useLatest`

useLatest is useRef plus the "keep me in sync" effect. If you've ever written this:

const textRef = useRef(text);
useEffect(() => { textRef.current = text; }, [text]);

…that's useLatest(text), minus the layout-effect timing detail above. It's also strictly more honest than the other common workaround — copying state into a ref inside the setter (setText(v); textRef.current = v;) — which silently breaks the moment anything else updates text (a reset button, a prop, a form library).

useLatest vs useEvent vs useEffectEvent

Now the neighbours. All three exist to defeat stale closures; they differ in what they wrap.

useLatest(value) wraps a value and gives you a ref. You read .current inside whatever callback you already have.
useEvent(fn) wraps a function and gives you a stable function that always calls the latest fn. Internally it's useLatest(fn) plus useCallback(() => ref.current(...args), []). Use it when the callback itself is what you hand to a child, an effect, or a subscription and you want its identity to never change.
useEffectEvent (React 19.2+) is the built-in version of useEvent, restricted to being called from effects — the returned function is not stable and must not be passed as a prop or added to dependency arrays.

The rule of thumb: if you're wrapping a function, use useEvent; if you're wrapping a value, use useLatest. They compose — the classic "subscribe once, react to fresh state" is often one useEvent for the handler, or one useLatest per value it reads, and either is fine. Where useLatest wins outright is when the callback isn't yours to wrap: an SDK's onChange, a promise continuation, an Observer you construct once.

Patterns

After an `await`

The intro's autosave is the shape: any handler that awaits and then needs to know whether the world moved on. A second common variant is the request race in a handler rather than an effect:

function Search() {
  const [query, setQuery] = useState("");
  const [results, setResults] = useState<Item[]>([]);
  const latestQuery = useLatest(query);

  async function onChange(e: React.ChangeEvent<HTMLInputElement>) {
    const q = e.target.value;
    setQuery(q);
    const items = await api.search(q);
    if (latestQuery.current !== q) return; // a newer keystroke won — drop this response
    setResults(items);
  }

  return <input value={query} onChange={onChange} />;
}

Inside a useEffect you'd use the React-docs let ignore = false cleanup flag for this. Event handlers have no cleanup slot, so the ref carries the "am I still relevant?" check instead. (For debouncing the calls themselves, see useDebounceFn — that's a different problem.)

Subscriptions you create once

Anything expensive or stateful to set up — a map, a chart, a WebSocket, a ResizeObserver — should be created once and read fresh state, not be torn down and rebuilt on every keystroke:

function PinMap({ filters }: { filters: Filters }) {
  const container = useRef<HTMLDivElement>(null);
  const latestFilters = useLatest(filters);

  useEffect(() => {
    const map = new mapboxgl.Map({ container: container.current!, style: STYLE });
    map.on("moveend", () => {
      loadPins(map.getBounds(), latestFilters.current); // fresh filters, map built once
    });
    return () => map.remove();
  }, []); // ✅ empty deps are honest here — nothing inside is stale

  return <div ref={container} />;
}

Without the ref, the choice is filters in the deps (map destroyed and recreated on every filter change — flicker, lost viewport, re-download of tiles) or an empty deps array with a lint warning and a bug. useLatest gives you a third option: the effect genuinely depends on nothing, because it reads through a ref that's always current.

Timers

setTimeout and setInterval are the textbook stale-closure factories:

function Toast({ message, onDismiss }: { message: string; onDismiss: () => void }) {
  const [paused, setPaused] = useState(false);
  const latestPaused = useLatest(paused);

  useEffect(() => {
    const id = setTimeout(() => {
      if (!latestPaused.current) onDismiss(); // hovered at the 5s mark? stay open
    }, 5000);
    return () => clearTimeout(id);
  }, []);

  return <div onMouseEnter={() => setPaused(true)} onMouseLeave={() => setPaused(false)}>{message}</div>;
}

For anything beyond a one-off, don't hand-roll it: useTimeoutFn and useInterval already keep the callback fresh via useLatest and add pause/resume/immediate on top — the previous post in this series, React useInterval Hook, walks through exactly that.

Where @reactuses/core uses it

If you want to see the pattern in production code, useLatest is the quiet workhorse behind a large chunk of the library. useEventListener wraps your handler in it so addEventListener runs once per element, not once per render. useClickOutside, useIntersectionObserver, useResizeObserver and useMutationObserver all construct their observer once and call savedCallback.current from inside it. useRafFn reads the latest frame callback without cancelling the animation loop. useUnmount uses it so the cleanup you passed on the first render doesn't run with first-render values on unmount. Same five lines, every time.

Gotchas Worth Knowing

It's not reactive. Writing to or reading from .current never triggers a re-render. If a change should show up on screen, it belongs in state — useLatest is for callbacks that read, not for values that display.
Don't read it during render. Because the ref is updated in a layout effect, during render it lags one commit behind. That's by design and never matters when you read it from callbacks; it matters instantly if you put latest.current in JSX or in a useMemo. Read the value directly there.
Don't put it in a dependency array expecting it to trigger anything. The ref's identity is stable for the component's lifetime, so [latestFoo] is equivalent to []. That's a feature — it means the effect that reads it never re-runs because of it — but it also means you can't use it to react to changes.
The lag window is real, and tiny. Between render and the layout effect commit, .current is last render's value. Nothing user-visible runs in that window (no events, no timers, no passive effects), so it's a non-issue in practice, and it's the price of never leaking a discarded render into the ref.
Sometimes a restart is what you want. If your effect should re-run when a value changes — reconnect a socket when the roomId changes — put roomId in the deps like normal. Use useLatest only for values the callback should read without causing a restart. Mixing the two in one effect ([roomId] in deps, latestFilters.current inside) is completely normal.
SSR-safe. It's a ref and an isomorphic layout effect; nothing touches window, and there's no hydration mismatch because it never renders anything.

When Not to Use useLatest

The value is displayed → useState, always.
You're wrapping a function to hand to a child or effect → useEvent (or useEffectEvent on React 19.2+ if it stays inside an effect).
You want the value from the previous render → usePrevious — the mirror image of useLatest.
You want to know whether the component is still mounted before setting state after an await → useMountedState is that exact boolean.
The "stale" value is a timer or DOM callback → you probably want useInterval, useTimeoutFn or useEventListener, which already do the useLatest dance for you.

Takeaways

A callback that outlives its render — timer, await, subscription, SDK hook — sees the props and state of the render that created it. That's a closure doing its job; it's a bug only when you needed now and got then.
useLatest is a ref kept in sync with a value in a layout effect: always current from any callback, never causes a re-render, never changes identity, never leaks a discarded render.
Value → useLatest. Function → useEvent. Displayed → useState. Previous render → usePrevious.
Read .current from callbacks, never from render, and keep genuine restart triggers (roomId, url) in your dependency array — useLatest is for what the callback should read through, not for what should restart it.

useLatest, useEvent, usePrevious, and 110+ other SSR-safe, TypeScript-first hooks live in @reactuses/core — one install, tree-shakeable, no dependencies to babysit.

npm install @reactuses/core

React useInterval Hook: setInterval Without Stale Closures (2026)

ReactUse — Sat, 15 Aug 2026 08:48:09 +0000

Every React developer writes this component once, and it never does what they expect:

function Counter() {
  const [count, setCount] = useState(0);

  useEffect(() => {
    const id = setInterval(() => setCount(count + 1), 1000);
    return () => clearInterval(id);
  }, []);

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

It goes 0, 1… and stays at 1 forever. The interval callback was created on the first render, where count was 0, and an empty dependency array means it never sees another render. setCount(0 + 1) runs every second and nothing changes. This is the single most searched React timer bug, and the "fixes" people find — add count to the deps (now the interval is torn down and recreated every second), use the functional updater (works, until the callback needs anything other than the previous count) — all fight the underlying mismatch: setInterval is imperative and lives outside React's render cycle, while everything it wants to read lives inside it.

Dan Abramov's 2019 essay Making setInterval Declarative with React Hooks gave the mismatch a proper solution: a useInterval hook that keeps the latest callback in a ref and never restarts the timer just because your component re-rendered. useInterval from @reactuses/core is that idea, plus the pieces you end up needing in a real app — null to pause, pause() / resume() controls, an immediate option, and cleanup that survives StrictMode. This post covers how it works, the two ways to pause, dynamic polling intervals, the background-tab problem, and when a different timer hook is the right call.

Quick Start

npm install @reactuses/core

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

function Counter() {
  const [count, setCount] = useState(0);

  useInterval(() => {
    setCount(count + 1); // reads the CURRENT count — no functional updater needed
  }, 1000);

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

That's the broken component from the intro, fixed by swapping useEffect + setInterval for useInterval. The callback can read any prop or state directly, the timer is created once and cleared on unmount, and there's no dependency array to get wrong.

The signature is useInterval(callback, delay, options?) — delay in milliseconds, or null to pause — and it returns { isActive, pause, resume } for the cases where you want manual control.

Why setInterval and React Don't Get Along

Under the hood there are three separate problems, and the hook solves each one differently:

Stale closures. setInterval holds one function reference for its whole life. That function closed over one render's props and state. Every later render creates a fresh closure — which the running interval never sees.
Restart-on-render. The obvious fix is to make the effect depend on whatever the callback reads: useEffect(..., [count]). Now the interval is correct, but it is cleared and re-created on every change — the timing resets each time, and with a fast-changing dependency the tick may never fire at all.
Lifecycle. You have to clear the interval on unmount, clear it again on StrictMode's dev remount, and — the part that turns into a small state machine — decide how to pause it: a second piece of state, an if around setInterval, and dependencies that now include the pause flag.

Here's what a correct hand-rolled version looks like once all three are handled — a ref for the latest callback, an effect keyed only on delay, and null as the pause signal:

function useIntervalManual(callback: () => void, delay: number | null) {
  const savedCallback = useRef(callback);

  useLayoutEffect(() => {
    savedCallback.current = callback; // always the latest render's closure
  }, [callback]);

  useEffect(() => {
    if (delay === null) return;
    const id = setInterval(() => savedCallback.current(), delay);
    return () => clearInterval(id);
  }, [delay]);
}

That's essentially the core of @reactuses/core's useInterval — it uses useLatest for the ref and adds controls on top. Two properties fall out of the design, and they're the ones to internalize:

Changing the callback never restarts the timer. Re-render as often as you like, pass inline arrow functions, read whatever state you want — the ref is updated, the interval keeps its rhythm.
Changing delay does restart it. delay is the only dependency, so 5000 → 1000 clears the old interval and starts a fresh one. That resets the phase: the next tick is a full delay away from the moment the change committed. Usually right (it's how backoff works, below), occasionally surprising if you were expecting the in-flight tick to complete.

Pausing: `null` vs. `pause()` / `resume()`

There are two ways to stop the interval, and picking the right one keeps your component simple.

Declarative — pass null as the delay. When "should this be running?" is derivable from state or props, encode it in the delay expression and let the hook follow:

function LivePrice({ symbol, live }: { symbol: string; live: boolean }) {
  const [price, setPrice] = useState<number | null>(null);

  useInterval(
    async () => setPrice(await fetchPrice(symbol)),
    live ? 5000 : null, // false → paused, true → polling every 5s
  );

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

Flip live and the interval clears or restarts. No effect, no ref, no extra state.

Imperative — controls: true and the returned handles. When starting and stopping is a user action rather than a derived condition (a Start/Stop button, "pause while this modal is open"), opt out of automatic starting and drive it yourself:

function Stopwatch() {
  const [elapsed, setElapsed] = useState(0);
  const [running, setRunning] = useState(false);
  const startedAt = useRef(0);

  const { pause, resume } = useInterval(
    () => setElapsed(Date.now() - startedAt.current), // read the clock, don't count ticks
    100,
    { controls: true }, // don't start on mount — wait for resume()
  );

  const toggle = () => {
    if (running) {
      pause();
    } else {
      startedAt.current = Date.now() - elapsed;
      resume();
    }
    setRunning(!running);
  };

  return (
    <>
      <p>{(elapsed / 1000).toFixed(1)}s</p>
      <button onClick={toggle}>{running ? "Pause" : "Start"}</button>
    </>
  );
}

pause and resume have stable identities (safe in dependency arrays and event handlers), and the interval is still cleared on unmount even in controls mode — you can't leak a timer by forgetting. One honest note: isActive in the return value is a ref (isActive.current), not state — it won't re-render your component when it flips, which is why the example above keeps its own running state for the button label.

You can also mix the two: without controls, pause() still works as a temporary override, and the next delay change resumes automatically.

`immediate`: Fire Now, Then Every N ms

setInterval waits a full delay before its first call, which is almost never what you want for polling — the user stares at an empty screen for five seconds. immediate: true runs the callback synchronously when the interval starts, then keeps the schedule:

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

Note that "when the interval starts" includes every delay change — every time the delay value changes, the callback fires once right away and the schedule restarts. That's handy when a user changes the refresh rate, but it's exactly wrong for a failure-driven backoff (each widening of the delay would trigger another call on the spot), so leave immediate off there — see the next section.

Real-World Patterns

Polling with backoff

Because delay is a normal value, backoff is just state. On failure, widen the interval; on success, snap back:

function useJobStatus(jobId: string) {
  const [status, setStatus] = useState<Job | null>(null);
  const [delay, setDelay] = useState<number | null>(2000);

  useInterval(async () => {
    try {
      const job = await getJob(jobId);
      setStatus(job);
      if (job.done) setDelay(null);            // stop polling
      else setDelay(2000);                     // healthy → base rate
    } catch {
      setDelay((d) => Math.min((d ?? 2000) * 2, 60_000)); // back off, cap at 1 min
    }
  }, delay);

  return status;
}

Each setDelay restarts the interval with the new cadence — and because immediate is off, a failure waits the new, longer delay before trying again, which is the whole point. There's no timer bookkeeping anywhere in that hook — it's all "what should the delay be right now?".

Pause in background tabs (and offline)

Browsers throttle timers in hidden tabs — to roughly once per second, and Chrome drops to once per minute after a tab has been hidden for five minutes. Polling in a background tab therefore both wastes quota and fires at unpredictable times. The fix composes naturally with the null pattern using useDocumentVisibility and useOnline:

const visible = useDocumentVisibility() === "visible";
const online = useOnline();

useInterval(refresh, visible && online ? 10_000 : null, { immediate: true });

When the user comes back, delay flips from null to 10_000, the interval restarts, and immediate fetches fresh data right away — exactly the "resume and catch up" behavior you'd otherwise hand-code with visibilitychange listeners.

Clocks: schedule ticks, don't count them

setInterval drifts. Over a minute of "every 1000ms" you can lose a second or more, especially in throttled tabs. So don't accumulate time in the callback — use the interval only to trigger a re-render and read the real clock:

function Clock() {
  const [now, setNow] = useState(() => Date.now());
  useInterval(() => setNow(Date.now()), 1000);
  return <time>{new Date(now).toLocaleTimeString()}</time>;
}

The interval is allowed to be sloppy; the displayed value is always correct because it comes from Date.now(), not from ticks × 1000. Same rule for elapsed-time displays: store a start timestamp, render Date.now() - start.

When Not to Use useInterval

You want one delayed call, not a repeating one. That's useTimeoutFn — const [pending, start, stop] = useTimeoutFn(fn, ms) — or useTimeout if all you need is a re-render after N ms.
You're building a countdown display. useCountDown already does the seconds → hh:mm:ss math and completion callback on top of useInterval.
You're animating. Anything visual that should update every frame belongs in requestAnimationFrame, which is what useRafFn wraps — it syncs to the display refresh rate and pauses automatically in hidden tabs. A 16ms setInterval is not the same thing.
You're rate-limiting a handler, not scheduling one. Firing on the trailing edge of user input is useDebounceFn / useThrottleFn territory.
The "interval" is really server push. If the server can tell you when something changed, a Server-Sent Events stream via useEventSource beats polling on latency and cost.

You want…	Reach for
run `fn` every N ms, pause with `null` or `pause()`	`useInterval`
run `fn` once after N ms, with `start` / `stop`	`useTimeoutFn`
re-render once after N ms	`useTimeout`
`hh:mm:ss` countdown from N seconds	`useCountDown`
run `fn` every animation frame	`useRafFn`

Gotchas Worth Knowing

The callback reads the latest committed render. The ref is updated in a layout effect after each render, so a tick that fires mid-render sees the previous committed values — a non-issue in practice, but the reason the hook can't be "more current than React".
delay change = phase reset. Covered above; if you need to change the cadence without dropping the in-flight tick, keep the interval fixed and skip ticks in the callback instead.
immediate fires inside the effect, on mount and on every delay change. Under React 18+ StrictMode in dev, that means the immediate call happens twice on mount (mount → cleanup → mount). Make it idempotent, as with any effect.
async callbacks are fine — but overlap is on you. The hook doesn't wait for a returned Promise. If a fetch can take longer than delay, guard with an in-flight flag or use null to pause while a request is pending.
SSR-safe by construction. The timer is created inside an effect, so nothing runs on the server and there's no window access to guard.

Takeaways

The stuck-at-1 counter is a stale-closure bug: setInterval keeps the first render's callback. useInterval stores the latest callback in a ref, so the timer runs once and always sees current state.
Only delay restarts the interval — pass null to pause declaratively, or controls: true with pause() / resume() for user-driven start/stop.
immediate: true fires now-then-every-N; backoff is just setDelay(...); pause polling in hidden or offline tabs by folding useDocumentVisibility / useOnline into the delay expression.
Never accumulate time in an interval — read Date.now() — and reach for useTimeoutFn, useCountDown, or useRafFn when the job isn't "every N ms, forever".

useInterval, useTimeoutFn, useCountDown, and 110+ other SSR-safe, TypeScript-first hooks live in @reactuses/core — one install, tree-shakeable, no dependencies to babysit.

npm install @reactuses/core

React useFocus Hook: Track & Control Element Focus State (2026)

ReactUse — Fri, 14 Aug 2026 04:01:41 +0000

Focus is where interaction actually happens — the input receiving keystrokes, the button the keyboard user just tabbed to. Yet React gives you no state for it. document.activeElement knows the answer but never tells you when it changes, the autoFocus attribute fires once and can't be re-triggered, and reading focus for rendering — show hints while editing, float a label, validate after leaving — means wiring focus/blur listeners by hand on every field that needs it.

useFocus from @reactuses/core collapses all of that into one line: a live isFocused boolean your component just renders, plus a setter that focuses or blurs the element whenever your logic decides to.

Quick Start

npm install @reactuses/core

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

function SearchField() {
  const ref = useRef<HTMLInputElement>(null);
  const [isFocused, setFocused] = useFocus(ref);

  return (
    <div className={isFocused ? "field field--active" : "field"}>
      <input ref={ref} placeholder="Search hooks…" />
      {isFocused && <kbd className="hint">esc to clear</kbd>}
      <button onClick={() => setFocused(true)}>Jump to search</button>
    </div>
  );
}

That's the whole integration. The hook subscribes to the element's focus and blur events and mirrors them into state; setFocused(true) calls element.focus(), setFocused(false) calls element.blur(). One tuple, both directions — observe focus and command it.

Why Not autoFocus, activeElement, or Plain CSS?

Each of the built-in options covers a sliver of the problem:

CSS :focus / :focus-within is the right tool when the response is pure styling — a border color, a glow. Use it; it costs zero JavaScript and zero re-renders. The hook earns its place the moment focus drives logic or JSX: rendering a hints panel, deciding when to validate, pausing a ticker while the user types.
document.activeElement is a snapshot, not a subscription. Read it in render and it's stale by the next tab-press; nothing re-renders your component when focus moves.
autoFocus fires once, at mount, and that's the entire API. It can't focus on demand ("press / to search"), can't blur, and tells you nothing about the current state.
ref.current.focus() sprinkled in handlers works — until you also need to know whether the element is focused, and now you're maintaining listeners anyway.

The Manual Way — and Where It Bites

The hand-rolled version looks harmless:

// ⚠️ hand-rolled — works in the demo, leaks bugs in the app
function SearchField() {
  const ref = useRef<HTMLInputElement>(null);
  const [isFocused, setIsFocused] = useState(false);

  useEffect(() => {
    const el = ref.current;
    if (!el) return;
    const onFocus = () => setIsFocused(true);
    const onBlur = () => setIsFocused(false);
    el.addEventListener("focus", onFocus);
    el.addEventListener("blur", onBlur);
    return () => {
      el.removeEventListener("focus", onFocus);
      el.removeEventListener("blur", onBlur);
    };
  }, []);
  // …
}

Three problems hiding in fifteen lines:

Late-mounting targets never get wired. The if (!el) return guard runs once. If the input renders conditionally — inside a modal, behind a tab, after a loading state — the effect has already returned and no listener ever attaches. An empty dependency array can't express "re-run when the element appears."
It misses the initial state. If something focuses the element before your effect runs (an autoFocus attribute, a router's focus restoration), your state says false while the element sits there focused. You need a document.activeElement check on mount in addition to the listeners.
It's per-field boilerplate. Multiply those fifteen lines by every input in a form and the form file is mostly plumbing.

useFocus absorbs all three: targets can be lazy getters (() => document.querySelector(".modal input")) that re-resolve as the DOM changes, mount-time state is reconciled for you, and each field is one line.

The useFocus API

const [isFocused, setFocused] = useFocus(target, initialValue?);

target is flexible — pass whichever you have:

useFocus(ref);                                     // a ref object
useFocus(document.getElementById("search"));       // an element
useFocus(() => document.querySelector(".otp input")); // a lazy getter

SVG elements work too — the target type is HTMLElement | SVGElement, so a focusable <circle tabindex="0"> in a chart is fair game.

initialValue (default false) is declarative autofocus: pass true and the hook focuses the element on mount. Unlike the autoFocus attribute, it goes through the same code path as setFocused, works with getter targets, and leaves you holding the live state afterwards.

setFocused is imperative control with cleanup included: true → element.focus(), false → element.blur(). If the target doesn't exist yet, the call is a safe no-op instead of a crash.

Real Patterns

Floating labels — the label knows when to float

The material-style input: label sits inside the field, floats up when the field is active or has content.

function FloatingLabelInput({ label }: { label: string }) {
  const ref = useRef<HTMLInputElement>(null);
  const [isFocused] = useFocus(ref);
  const [value, setValue] = useState("");

  const floated = isFocused || value.length > 0;

  return (
    <label className="float-field">
      <span className={floated ? "float-label up" : "float-label"}>
        {label}
      </span>
      <input ref={ref} value={value} onChange={e => setValue(e.target.value)} />
    </label>
  );
}

CSS alone gets close with :focus-within + :placeholder-shown, but the moment the float condition involves app state — a controlled value, a validation flag — you need focus as state, and this is it.

Validate on blur, not on keystroke

Yelling "invalid email" at someone who has typed three characters is the classic form-UX failure. The fix is touched semantics — validate only after the user leaves the field:

function EmailField() {
  const ref = useRef<HTMLInputElement>(null);
  const [isFocused] = useFocus(ref);
  const [value, setValue] = useState("");
  const [touched, setTouched] = useState(false);

  useEffect(() => {
    if (isFocused) return;      // still editing — stay quiet
    if (value) setTouched(true); // left the field with content → judge it
  }, [isFocused, value]);

  const error = touched && !isFocused && !value.includes("@");

  return (
    <div>
      <input ref={ref} value={value} onChange={e => setValue(e.target.value)} />
      {error && <p className="error">That doesn't look like an email.</p>}
    </div>
  );
}

The isFocused transition is the touched signal — no onBlur prop threading, and the error clears itself the moment the user comes back to fix it.

Press `/` to search

Every documentation site does this, and setFocused plus useEventListener is the entire implementation:

function DocSearch() {
  const ref = useRef<HTMLInputElement>(null);
  const [isFocused, setFocused] = useFocus(ref);

  useEventListener("keydown", (e) => {
    if (e.key === "/" && !isFocused) {
      e.preventDefault();     // don't type the slash
      setFocused(true);
    }
    if (e.key === "Escape") setFocused(false);
  });

  return <input ref={ref} placeholder="Press / to search" />;
}

Note how both halves of the tuple earn their keep: isFocused guards against hijacking a / the user is legitimately typing into the field, and setFocused does the jump.

Autofocus that survives conditional rendering

Focusing the first field of a modal form, where the input doesn't exist until useDisclosure says so:

function RenameDialog({ open }: { open: boolean }) {
  const ref = useRef<HTMLInputElement>(null);
  useFocus(ref, true); // focuses on mount — which is when the dialog opens

  if (!open) return null;
  return (
    <dialog open>
      <input ref={ref} defaultValue="untitled.md" />
    </dialog>
  );
}

Because the component (and the hook) mounts when the dialog opens, initialValue: true fires at exactly the right moment — no setTimeout(…, 0) incantations.

useFocus vs Its Siblings

@reactuses/core ships three focus hooks at three zoom levels — pick by the question you're asking:

Hook	Answers	Reach for it when
`useFocus`	"is this element focused?" + control	per-field UI: labels, hints, validation timing, shortcuts
`useActiveElement`	"which element has focus, document-wide?"	form-level logic, focus debugging, roving-focus widgets
`useWindowFocus`	"is the tab/window focused at all?"	pausing polling or animations when the user switches away
CSS `:focus` / `:focus-visible`	styling only	any pure-CSS response — always try this first

The rule of thumb: one element → useFocus; whole document → useActiveElement; the browser window itself → useWindowFocus.

Production Notes

SSR is handled. There's no DOM on the server; the hook renders the initialValue you gave it and wires listeners after hydration — no typeof window guards in your code.
element.focus() scrolls. Browsers scroll a newly focused element into view. Autofocusing something below the fold on page load yanks the viewport — reserve initialValue: true for elements that are already where the user is looking (modals, inline editors).
Don't steal focus. Moving focus is an accessibility action, not a visual one: screen readers announce the newly focused element, and keyboard users lose their place. Focus in response to user intent (a shortcut, opening a dialog), never on a timer or a data refresh.
Blur sends focus to <body>. setFocused(false) doesn't restore focus to where it was before — after closing a dialog, hand focus back to the trigger button explicitly.
Style with :focus-visible, decide with isFocused. Keyboard-only focus rings are a solved CSS problem; keep the ring in CSS and spend the hook's state on logic. Related concerns compose the same way — clicks outside the field are useClickOutside, not a blur hack.

Takeaways

React has no focus state, and the primitives don't compose into one: document.activeElement isn't reactive, autoFocus is fire-once, and hand-rolled listeners miss late-mounting elements and pre-focused mounts. useFocus is the missing [isFocused, setFocused] tuple.
The setter is bidirectional control — true focuses, false blurs, safely no-oping if the element isn't there yet; initialValue: true is declarative autofocus that lands exactly at mount.
The killer patterns are timing patterns: float labels while editing, validate only after leaving, jump to search on /, focus the modal's first field the instant it exists.
Pure styling belongs to CSS :focus and :focus-visible — spend the hook on logic and JSX. And pick your zoom level: element → useFocus, document → useActiveElement, window → useWindowFocus.
Focus is an accessibility surface: move it on user intent, never steal it, and return it where it came from when you're done.

useFocus and 110+ other SSR-safe, TypeScript-first hooks live in @reactuses/core — one install, tree-shakeable, no dependencies to babysit.

npm install @reactuses/core

React useElementSize Hook: Track Element Width & Height with ResizeObserver (2026)

ReactUse — Thu, 13 Aug 2026 02:15:02 +0000

Media queries answer one question: how big is the viewport? But your components don't live in the viewport — they live in columns, cards, panels, and grid tracks. The same <ProductCard> is 900px wide in a full-width main column and 320px wide next to an open sidebar, on the same screen. And an element's size changes for a dozen reasons that never fire a window resize event: a sidebar collapses, an accordion expands, a font finishes loading, a flex sibling appears, content streams in.

Tracking any of that means ResizeObserver — the browser API built for exactly this — wrapped in the usual React ceremony of refs, effects, and cleanup. useElementSize from @reactuses/core reduces the whole thing to two numbers your component just renders: [width, height], live, for any element.

Quick Start

npm install @reactuses/core

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

function ChartCard() {
  const ref = useRef<HTMLDivElement>(null);
  const [width, height] = useElementSize(ref);

  return (
    <div ref={ref} className="chart-card">
      <Chart width={width} height={height} />
    </div>
  );
}

That's the entire integration. The hook attaches a ResizeObserver on mount, and because ResizeObserver reports once immediately on observe(), width and height populate right after first paint without a separate "measure on mount" pass. Every subsequent size change — window resize, sidebar toggle, content reflow — updates the state. Unmount cleans up the observer. No refs to observers, no disconnect() to forget.

Why Not window.innerWidth or a Media Query?

Because most element resizes have nothing to do with the window:

A collapsible sidebar opens and your main column loses 280px — viewport unchanged.
A user drags a split-pane divider.
An <img> above your element finishes loading and pushes everything down and reflows the column.
A filter empties a flex row and the survivors stretch.
A CSS transition animates a panel's width over 300ms.

Window-level tools are blind to all of it. useWindowSize and useMediaQuery are the right calls for page-level layout decisions — but a component that keys its layout on viewport width breaks the first time someone renders it in a narrow column on a wide screen.

CSS container queries deserve a mention here: if your response to size is pure styling, @container handles it with zero JavaScript and zero re-renders — use that. The hook earns its place the moment you need the number in JS: chart dimensions, canvas backing stores, virtualization math, or rendering a genuinely different component tree.

The Manual Way — and Where It Bites

Hand-rolling looks short enough:

// ⚠️ hand-rolled — works in the demo, leaks bugs in the app
function ChartCard() {
  const ref = useRef<HTMLDivElement>(null);
  const [size, setSize] = useState({ width: 0, height: 0 });

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

  return <div ref={ref}>…</div>;
}

Three problems hiding in ten lines:

Late-mounting targets never get observed. That if (!ref.current) return guard runs once, on mount. If the element renders conditionally — behind a loading state, a tab, a modal — the effect already returned and nothing ever attaches. You need the effect to re-run when the element appears, which an empty dependency array can't express.
The options-identity trap. Want { box: "border-box" }? That object literal is new every render. Put it in the effect's dependency array and you tear down and recreate the observer on every render; leave it out and the lint rule yells or a later edit silently stales it.
You read the wrong box. contentRect is the legacy field, kept for compatibility. The modern fields — borderBoxSize, contentBoxSize, devicePixelContentBoxSize — are arrays (elements can fragment across columns), and picking and summing the right one is more code than the observer itself.

useElementSize absorbs all three: for conditionally rendered elements you pass a lazy getter (() => document.querySelector(".panel")) and the hook re-resolves it every render, attaching the moment the element exists; options are deep-compared (inline literals are fine); and box selection — including fragment summation — is handled per spec.

The useElementSize API

const [width, height] = useElementSize(target, options?);

target is flexible — pass whichever you have:

useElementSize(ref);                                    // a ref object
useElementSize(document.getElementById("hero"));        // an element
useElementSize(() => document.querySelector(".panel")); // a lazy getter

options is a standard ResizeObserverOptions — one field, box, three values. And because the hook deep-compares options internally, useElementSize(ref, { box: "border-box" }) with an inline literal does not churn the observer every render.

Which box should you measure?

content-box (default) — the content area only: padding and border excluded. This is "how much room does my content have," the right box for laying out children, charts, and column math.
border-box — padding and border included; matches offsetWidth/offsetHeight and how much space the element occupies in layout. Reach for it when coordinating with siblings or overlays.
device-pixel-content-box — the content box in physical device pixels. This one is special.

The crisp-canvas trick

A <canvas> whose backing store doesn't match its physical pixel size renders blurry on 2× displays. The folk fix — multiply CSS pixels by devicePixelRatio — rounds wrong under browser zoom and fractional DPR. device-pixel-content-box hands you the exact integer the compositor uses:

function SharpCanvas() {
  const ref = useRef<HTMLCanvasElement>(null);
  const [width, height] = useElementSize(ref, {
    box: "device-pixel-content-box",
  });

  useEffect(() => {
    const canvas = ref.current;
    if (!canvas || !width) return;
    canvas.width = width;   // physical pixels — pixel-perfect at any DPR or zoom
    canvas.height = height;
    draw(canvas.getContext("2d")!);
  }, [width, height]);

  return <canvas ref={ref} style={{ width: "100%", height: 300 }} />;
}

(Safari doesn't support device-pixel-content-box yet — the hook falls back to contentRect there, so degrade gracefully rather than assuming physical pixels everywhere.)

Real Patterns

Container-query components — breakpoints on the element, not the screen

function ProductCard() {
  const ref = useRef<HTMLDivElement>(null);
  const [width] = useElementSize(ref);

  const layout =
    width >= 640 ? "horizontal" : width >= 320 ? "compact" : "stacked";

  return (
    <article ref={ref} data-layout={layout}>
      {layout === "horizontal" ? <SideBySide /> : <Stacked />}
    </article>
  );
}

Drop this card in a sidebar, a modal, or a full-width list and it adapts to its own space — no prop-drilling a variant from whoever happens to know the context. Again: if the difference were only CSS, @container does this cheaper. This pattern is for when the component tree changes.

Responsive charts that re-layout at rest

Chart libraries want pixel numbers, and re-computing a chart layout 60 times a second while the user drags a splitter is wasted work. Let CSS stretch the canvas visually and settle the real re-layout with useDebounce:

const ref = useRef<HTMLDivElement>(null);
const [rawWidth, rawHeight] = useElementSize(ref);
const width = useDebounce(rawWidth, 150);
const height = useDebounce(rawHeight, 150);

// <ExpensiveChart width={width} height={height} /> re-lays-out
// once the drag stops, not on every frame of it.

How many columns fit?

Grid math that CSS can't do — because the answer feeds props, not styles:

const [width] = useElementSize(ref);
const columns = Math.max(1, Math.floor(width / 280));

return <VirtualGrid columns={columns} items={items} />;

useElementSize vs Its Siblings

@reactuses/core ships a small family of measurement hooks built on the same observer core — pick by what you need back:

Hook	Returns	Reach for it when
`useElementSize`	`[width, height]`	you need dimensions, nothing else
`useMeasure`	full `contentRect` (`x/y/top/left/…`) + a `stop()`	you want the whole rect, or to stop observing on demand
`useElementBounding`	live `getBoundingClientRect` — updates on scroll and resize	you need where it is in the viewport, not just how big
`useResizeObserver`	your callback gets raw entries	side effects instead of state; imperative work per resize
`useWindowSize`	viewport `width/height`	page-level layout, not element-level

The rule of thumb: useElementSize for dimensions, useElementBounding for position (tooltips, popovers, scroll-linked effects), useResizeObserver when you'd rather run code than store state.

Production Notes

SSR is handled. There's no DOM on the server, so the hook renders [0, 0] and attaches the observer after hydration — no typeof window guards in your code. Plan for the zero-frame: gate expensive children with if (!width) return <Skeleton /> rather than letting a chart lay out at 0×0.
The first real value arrives via the observer's initial report — one extra render right after mount. That's the cost of correctness; don't fight it.
Beware self-referential loops. If the content you render from the measured width changes the element's own width, you've built a resize feedback loop (ResizeObserver loop completed with undelivered notifications in the console). Fix it by measuring a parent whose size you don't alter, or clamping the derived values.
Fragmented layouts are summed correctly. In multi-column or paginated contexts an element's box can fragment; the hook sums inlineSize/blockSize across fragments per spec instead of reading only the first one.
Every hook call is one observer. Measuring 500 virtualized rows individually means 500 observers — at that scale, drop down to a single useResizeObserver on the container, or observe one prototype row.

Takeaways

Element size ≠ window size. Sidebars, split panes, streaming content, and font loads all resize elements without touching the viewport — only a ResizeObserver sees them, and useElementSize serves it as plain [width, height] state.
The box option picks what you measure: content-box for content math (default), border-box for layout footprint, device-pixel-content-box for pixel-perfect canvases at any DPR or zoom.
Targets can be refs, elements, or lazy getters — use a getter for conditionally rendered elements; inline options don't churn the observer thanks to deep comparison — the bugs every hand-rolled version has, pre-fixed.
Pure-CSS response to size? Use @container queries. The hook is for when the number drives JavaScript: charts, canvas, virtualization, or swapping component trees.
Need position too? That's useElementBounding. The full rect plus manual stop? useMeasure. Raw entries? useResizeObserver.

useElementSize and 110+ other SSR-safe, TypeScript-first hooks live in @reactuses/core — one install, tree-shakeable, no dependencies to babysit.

npm install @reactuses/core

React useEventSource Hook: Server-Sent Events with Auto-Reconnect (2026)

ReactUse — Wed, 12 Aug 2026 07:06:05 +0000

Live notifications, deployment logs, stock tickers, AI responses streaming in token by token — none of these need a WebSocket. They're all one-directional: the server talks, the client listens. The browser has had a native protocol for exactly this since 2011 — Server-Sent Events (SSE) — and it runs over plain HTTP, passes through proxies and load balancers untouched, and reconnects automatically when the connection drops.

What SSE doesn't have is a good React story. The native EventSource API is imperative: you construct it, attach listeners, and must tear it down at exactly the right moment — the classic effect-lifecycle minefield. useEventSource from @reactuses/core turns the whole thing into declarative state: data, status, and error your component just renders. This post covers the hook's full API, the reconnect behavior that native EventSource gets subtly wrong, and useFetchEventSource — the fetch-based variant you'll need the moment your stream requires an Authorization header or a POST body, which in 2026 means every AI-completions endpoint.

Quick Start

npm install @reactuses/core

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

function DeploymentLog() {
  const { data, status } = useEventSource("/api/deploy/stream");

  return (
    <div>
      <span>{status === "CONNECTED" ? "🟢 live" : "🟡 connecting…"}</span>
      <pre>{data}</pre>
    </div>
  );
}

That's a complete live-updating component. The hook opens the connection on mount, updates data on every message, exposes the connection lifecycle as status ("CONNECTING" | "CONNECTED" | "DISCONNECTED"), and closes the stream when the component unmounts. No refs, no listeners, no cleanup function to forget.

What SSE Actually Is (60 Seconds)

Server-Sent Events is just an HTTP response that never finishes. The server replies with Content-Type: text/event-stream and writes messages as plain text, separated by blank lines:

data: {"price": 101.42}
id: 7

event: trade
data: {"symbol": "ACME", "qty": 200}
id: 8

Three field types matter:

data: — the payload (always a string; JSON-encode structured data yourself).
event: — an optional event name, so one stream can carry multiple channels.
id: — an optional event ID. The browser remembers the last one and sends it back as a Last-Event-ID header when it reconnects, so a well-built server can resume where the client left off.

Because it's plain HTTP, SSE works through corporate proxies, CDNs, and HTTP/2 multiplexing without the upgrade-handshake drama WebSockets sometimes hit. The trade-off: it's server → client only, and the native browser API can only send GET requests with no custom headers. Keep that limitation in mind — it's the reason the second hook in this post exists.

The Manual Way — and Where It Bites

Wiring EventSource by hand looks manageable:

// ⚠️ hand-rolled — three bugs waiting to happen
function Ticker() {
  const [price, setPrice] = useState<string | null>(null);

  useEffect(() => {
    const es = new EventSource("/api/prices");
    es.onmessage = e => setPrice(e.data);
    return () => es.close();
  }, []);

  return <span>{price}</span>;
}

The problems show up in production, not in the demo:

Reconnect is infinite and invisible. When the server drops the connection, EventSource retries forever, silently. If your API is down, every open tab hammers it every few seconds until the heat death of the universe — and you have no state telling the UI "we're offline" so you can show a banner or give up.
Errors are opaque. onerror gives you a bare Event — no status code, no reason. If you don't track connection state yourself, your UI happily shows stale data as if it were live.
Named events need manual bookkeeping. Every event: trade line requires its own addEventListener("trade", …) and a matching removeEventListener in cleanup. Miss one and you leak listeners across React 18 StrictMode's mount-unmount-mount cycle.

None of this is hard, exactly. It's just easy to get 90% right — which is the worst kind of wrong.

The useEventSource API

Everything the manual version does badly, as returned state:

const { data, event, status, error, lastEventId, open, close, eventSourceRef } =
  useEventSource(url, events?, options?);

data: string | null — payload of the most recent message.
event: string | null — the name of the last named event received (see below).
status — "CONNECTING" | "CONNECTED" | "DISCONNECTED". Render it; that's your live-indicator.
error: Event | null — the last connection error, cleared on successful reconnect.
lastEventId: string | null — the id: field of the last message, i.e. your resume cursor.
open() / close() — manual control. close() is explicit: it also disables auto-reconnect, so "user clicked pause" stays paused. open() reconnects and resets the retry counter.
eventSourceRef — escape hatch to the raw EventSource instance if you need it.

Named events, declaratively

Pass the event names you care about as the second argument, and the hook registers — and cleans up — every listener for you:

const { data, event } = useEventSource("/api/stream", ["trade", "quote"]);

// event === "trade" | "quote" | null — which channel data came from
useEffect(() => {
  if (event === "trade") appendTrade(JSON.parse(data!));
}, [data, event]);

Auto-reconnect with a budget

The autoReconnect option replaces EventSource's silent infinite retry with a policy you choose:

const { status } = useEventSource("/api/notifications", [], {
  autoReconnect: {
    retries: 5,        // give up after 5 attempts (or pass a () => boolean)
    delay: 2000,       // wait 2s between attempts
    onFailed: () => toast.error("Live updates unavailable — refresh to retry"),
  },
});

retries defaults to -1 (retry forever, matching native behavior), but now it's a decision rather than a surprise, and onFailed gives you the moment to tell the user. Pair it with status === "DISCONNECTED" to render a degraded-mode UI instead of silently stale numbers.

Connect lazily

By default the hook connects on mount. Pass immediate: false to wait for user intent:

const { status, open, close } = useEventSource("/api/live-scores", [], {
  immediate: false,
});

<button onClick={status === "CONNECTED" ? close : open}>
  {status === "CONNECTED" ? "Pause live scores" : "Go live"}
</button>

The Wall Every SSE Tutorial Hits: Auth Headers

Here is the native API's dirty secret: new EventSource(url) cannot send custom headers. No Authorization: Bearer …, no X-Api-Key, nothing. Your options with the native API are cookies (withCredentials: true) or a token in the query string — one of which doesn't work cross-domain with modern cookie policies, and the other of which lands your token in every access log between the browser and your server.

It also can't POST. That matters because the biggest SSE consumers of 2026 — OpenAI-style AI completion endpoints — are all POST /v1/chat/completions with a JSON body and a bearer token, streaming back text/event-stream. The native EventSource API literally cannot call them.

useFetchEventSource solves this by speaking SSE over fetch (built on Microsoft's battle-tested fetch-event-source parser), which means the full request is yours to shape:

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

const { data, status, error } = useFetchEventSource("/api/v1/chat/completions", {
  method: "POST",
  headers: { Authorization: `Bearer ${token}` },
  body: JSON.stringify({ model: "gpt-5", messages, stream: true }),
  autoReconnect: { retries: 3, delay: 1000 },
});

Same return shape as useEventSource — data, event, status, error, lastEventId, open, close — so switching between the two is a one-line change, not a rewrite.

Streaming an AI response, token by token

The onMessage callback is the natural place to accumulate a streamed completion:

function Answer({ prompt }: { prompt: string }) {
  const [text, setText] = useState("");

  const { status } = useFetchEventSource("/api/ask", {
    method: "POST",
    headers: { Authorization: `Bearer ${token}` },
    body: JSON.stringify({ prompt }),
    onMessage: msg => {
      if (msg.data === "[DONE]") return;
      const delta = JSON.parse(msg.data).choices[0]?.delta?.content ?? "";
      setText(prev => prev + delta);
    },
    onError: err => {
      if (isRateLimit(err)) return 5000; // return a number = retry after N ms
    },
  });

  return <Markdown>{text}{status === "CONNECTED" && "▌"}</Markdown>;
}

Two details worth stealing: returning a number from onError overrides the reconnect delay for that attempt (perfect for Retry-After-style backoff), and the functional setText(prev => …) update means token order survives React's batching.

Native or fetch-based — which one?

	`useEventSource`	`useFetchEventSource`
Transport	native `EventSource`	`fetch` + stream parser
Custom headers / bearer auth	❌	✅
POST with body	❌	✅
Auto `Last-Event-ID` resume	✅ built-in	your server's job
Extra bundle weight	zero	small parser dependency
Reach for it when…	same-origin or cookie-auth streams	AI APIs, token auth, request bodies

Simple rule: start with useEventSource; the moment you type the word Authorization, switch.

Production Notes

SSR is handled. Both hooks touch EventSource/fetch only inside effects, so they render harmlessly on the server — no typeof window guards in your code. First paint shows status: "DISCONNECTED", then the client connects.
Pause hidden tabs. A dashboard left open in a background tab keeps its stream (and your server's connection budget) alive. Combine with useDocumentVisibility to close() when hidden and open() on return — the Last-Event-ID handshake makes resume cheap.
One tab streams, the rest listen. Browsers cap concurrent connections per origin over HTTP/1.1 (~6), and every open tab with an SSE stream burns one. The classic fix: hold the stream in one tab and fan messages out with useBroadcastChannel. (Or serve over HTTP/2, where streams multiplex.)
Don't reconnect into a dead network. useNetwork or the smaller useOnline tells you the browser is offline — gate your retry UI on it instead of burning the retry budget while the laptop is in a tunnel.

When SSE Is the Wrong Tool

The client needs to talk back on the same channel — chat where you send messages, multiplayer cursors, collaborative editing. That's bidirectional; use a WebSocket.
Updates are rare. A value that changes a few times an hour doesn't justify a held-open connection — poll it, or refetch on focus with your data library.
You're delivering one payload. If the response ends when the data arrives, that's just fetch. SSE earns its keep only when the stream outlives the request.
Binary data. SSE is UTF-8 text. Ship binary over WebSocket or chunked fetch instead of base64-ing it through a text stream.

Takeaways

SSE is the simplest real-time transport: one long-lived HTTP response, native browser support, automatic resume via Last-Event-ID — right for every server-to-client feed.
useEventSource turns the imperative EventSource lifecycle into rendered state (data / status / error), handles named-event listener cleanup, and replaces invisible infinite retry with a reconnect policy you set — retries, delay, onFailed.
Native EventSource can't send an Authorization header or a POST body. useFetchEventSource can — same API shape, fetch-based transport — and it's the piece you need for streaming AI completions.
close() means stay closed (no auto-reconnect); open() resets the retry budget. Wire them to visibility and network state for streams that behave like a good citizen.

useEventSource, useFetchEventSource, and 110+ other SSR-safe, TypeScript-first hooks live in @reactuses/core — one install, tree-shakeable, no dependencies to babysit.

npm install @reactuses/core

React useMount Hook: Run an Effect Once on Mount (2026)

ReactUse — Tue, 11 Aug 2026 02:51:06 +0000

"Run this once, when the component appears." It's the single most common effect in React — focus an input, fire an analytics event, open a connection, read from a browser API. The idiom everyone reaches for is useEffect with an empty dependency array:

useEffect(() => {
  trackPageView("/checkout");
  // eslint-disable-next-line react-hooks/exhaustive-deps
}, []);

It works, but look at what it costs: an empty array you must remember (forget it and the effect runs on every render), a lint suppression comment whenever the effect touches anything, and — worst of all — zero stated intent. useEffect(fn, []) says how; it never says why. Six months later, a teammate adds a dependency to that array "to fix the lint warning" and your run-once effect quietly becomes a run-on-change effect.

useMount from @reactuses/core is the named version of this idiom: useMount(fn) runs fn exactly once per mount, and the name is the documentation. This post covers what it actually compiles down to, the React 18+ StrictMode double-run that surprises everyone the first time, the subtle stale-closure bug in hand-rolled unmount cleanups (and how useUnmount dodges it), async work on mount, and — just as important — the cases where you should not use it.

Quick Start

npm install @reactuses/core

import { useMount, useUnmount } from "@reactuses/core";
import { useRef } from "react";

function SearchBox() {
  const inputRef = useRef<HTMLInputElement>(null);

  useMount(() => {
    inputRef.current?.focus();
  });

  useUnmount(() => {
    console.log("search box removed");
  });

  return <input ref={inputRef} placeholder="Search…" />;
}

No dependency array, no lint comment, and the reader knows the intent before reading the body: this runs on mount, full stop.

What useMount Actually Is

No magic — here is the entire implementation, minus a dev-only type check:

export const useMount = (fn: () => void) => {
  useEffect(() => {
    fn?.();
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, []);
};

That's it: useEffect with an empty array, wrapped once so you never write the array or the suppression comment again. Three things fall out of this five-line definition:

Timing is useEffect timing. The callback fires after the component is committed to the DOM — after first paint, browser APIs available. It is not useLayoutEffect; if you need to measure and mutate before paint, reach for a layout effect instead.
It is SSR-safe by construction. Effects simply never run on the server, so useMount is the natural home for window/document access in SSR apps — the same guarantee the manual useEffect(fn, []) gives you, with the intent spelled out.
The return value is ignored. useMount calls fn?.() and discards the result — it does not forward a returned function to React as cleanup. Cleanup belongs to useUnmount (below). A side effect of this design: passing an async function is safe, which is more than you can say for raw useEffect (more on that in a minute).

One consequence to internalize: because the dependency array is empty, the callback closes over first-render values. Props and state read inside useMount are frozen at their initial values. For a mount effect that's almost always what you want — but if you find yourself wanting fresh values inside, that's the signal you actually want useEffect with dependencies, or a useLatest ref.

The StrictMode Gotcha: "Why Does My Mount Effect Run Twice?"

Search "useEffect runs twice" and you'll find a decade of confusion. Here's the short version: since React 18, <StrictMode> in development deliberately mounts every component, unmounts it, and mounts it again. Any mount effect — useEffect(fn, []), useMount, doesn't matter — runs twice in dev. In production it runs once.

React does this on purpose, to surface effects that don't clean up after themselves. The official guidance is: don't fight the double-run, make the effect idempotent — running it twice should be harmless because the cleanup undoes the first run:

useMount(() => {
  const controller = new AbortController();
  fetch("/api/config", { signal: controller.signal }).then(applyConfig);
  // pair with useUnmount(() => controller.abort())
});

But some effects are genuinely once-only, and running them twice is a real bug, not a hygiene warning: an analytics beacon fires twice, a welcome toast pops twice, a payment-intent gets created twice in dev and QA files a ticket. For those, @reactuses/core ships useOnceEffect:

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

useOnceEffect(() => {
  trackPageView("/checkout"); // fires once, even under StrictMode
});

The trick inside is elegant: useOnceEffect records each effect function in a WeakSet before running it. StrictMode's remount re-invokes the same effect function instance from the same render, so the second invocation finds it already recorded and bails. Genuine remounts (the component actually left and came back) create a fresh function and run again — exactly the semantics "once per mount, ignoring StrictMode's rehearsal" implies.

Rule of thumb: useMount + idempotent by default; useOnceEffect when a double-fire is observable to a user or a backend.

useUnmount — and the Stale-Closure Trap It Avoids

The obvious hand-rolled unmount cleanup has a bug most people ship without noticing:

// ⚠️ hand-rolled version
useEffect(() => {
  return () => {
    saveDraft(draft); // draft from the FIRST render — always empty!
  };
}, []); // empty deps ⇒ the cleanup closure was created on render #1

The cleanup function was created on the first render, so it captured the first render's draft. When the component unmounts three minutes and forty keystrokes later, it saves an empty string. The "fix" of adding draft to the deps is worse — now the cleanup runs on every keystroke, not on unmount.

useUnmount solves this properly. Internally it stores your callback in a useLatest ref that's updated every render, and the unmount cleanup calls through the ref:

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

function Composer() {
  const [draft, setDraft] = useState("");

  useUnmount(() => {
    saveDraft(draft); // ✅ the draft as of the LAST render
  });

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

Your callback runs exactly once, at unmount, and sees the latest state. This is the concrete reason to prefer useUnmount over the return () => {} idiom whenever the cleanup reads state or props — it's not sugar, it's a bug fix.

Async Work on Mount

Raw useEffect famously rejects async functions — useEffect(async () => {...}, []) hands React a Promise where it expects a cleanup function, and you get a warning plus a skipped cleanup. Because useMount discards the callback's return value, an async callback is perfectly fine:

useMount(async () => {
  const user = await fetchCurrentUser();
  setUser(user);
});

One thing this doesn't give you is protection against the component unmounting mid-await — calling setUser after unmount is harmless in React 18+ but often still not what you want (you may be writing to state that a remounted instance will clobber). Two library answers:

useMountedState returns an isMounted() function backed by a ref — check it after each await:

  const isMounted = useMountedState();

  useMount(async () => {
    const user = await fetchCurrentUser();
    if (isMounted()) setUser(user);
  });

useAsyncEffect generalizes the pattern for effects with dependencies, handing your async body a liveness check and supporting cleanup.

For real data fetching with caching and retries you'll outgrow both — that's React Query / SWR territory, or your framework's loaders. useMount is for the one-shot imperative stuff around the edges.

The Mirror Image: Skipping the Mount

Sometimes you want the opposite — react to changes but not to the initial mount. Sync a filter to the URL, but don't rewrite the URL on first load; show "settings saved" on change, but not on arrival. That's useUpdateEffect, and its primitive sibling useFirstMountState which simply tells you whether this is the first render:

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

useUpdateEffect(() => {
  syncFilterToUrl(filter); // runs on filter changes, skips the mount
}, [filter]);

Together the four hooks cover the whole lifecycle vocabulary that classes used to spell componentDidMount / componentDidUpdate / componentWillUnmount:

You want to run code…	Reach for
once, after the component appears	`useMount`
once, even under StrictMode's dev double-run	`useOnceEffect`
when the component is removed, seeing latest state	`useUnmount`
on updates only, skipping the first render	`useUpdateEffect`
conditionally, based on "is this the first render?"	`useFirstMountState`

When Not to Use useMount

Honesty section. useMount is intent-naming sugar over a real React primitive, and the primitive is sometimes the right call:

The effect reads a prop or state that can change. If roomId changes and you need to reconnect, that is useEffect(connect, [roomId]) — a mount hook here is a synchronization bug wearing a convenience API. The empty array isn't ceremony in that case; it's wrong.
You're fetching server data for rendering. Framework loaders, React Query, SWR — anything with caching, deduplication, and revalidation beats a fetch in a mount effect. React's own docs have walked away from "fetch in useEffect" as a primary pattern.
You need pre-paint measurement. useMount is post-paint. Measure-then-mutate work belongs in a layout effect.
The "mount event" is actually a user event. If code can run in the click handler that caused the component to appear, run it there — effects are for synchronizing with external systems, not a junk drawer.

The test is one question: would this code ever need to re-run while the component is alive? If the answer is any form of "yes, when X changes," you want useEffect and a dependency array. If it's a clean "no," useMount says so in a way [] never will.

Takeaways

useMount(fn) is useEffect(fn, []) with the intent in the name — no array to forget, no lint suppression, first-render closure semantics you should embrace, not fight.
In React 18+ dev StrictMode every mount effect runs twice. Make effects idempotent by default; use useOnceEffect when a double-fire is user- or backend-visible.
Hand-rolled return () => {} cleanups with empty deps capture first-render state — a real, shipping bug. useUnmount reads through a latest-ref and sees final state.
useMount accepts async callbacks (the return value is discarded); guard post-await state writes with useMountedState or use useAsyncEffect.
For change-only effects, useUpdateEffect is the mirror image.

useMount, useUnmount, useOnceEffect, and 110+ other SSR-safe, TypeScript-first hooks live in @reactuses/core — one install, tree-shakeable, no dependencies to babysit.

npm install @reactuses/core

React useEvent Hook: Stable Callbacks Without Stale Closures (2026)

ReactUse — Fri, 07 Aug 2026 03:59:18 +0000

Every React developer eventually meets the same fork in the road. You write an event handler that reads state, pass it to a child or an effect, and now you must choose: leave it as a plain inline function and watch every render create a new reference — breaking React.memo, re-running effects, re-subscribing listeners — or wrap it in useCallback and start playing dependency-array whack-a-mole, where one forgotten dependency means the handler sees state from three renders ago.

That second failure mode has a name — the stale closure — and it's arguably the most common React bug in production code. The fix has a name too: useEvent, proposed in an official React RFC in 2022, and available today as useEvent in @reactuses/core. It gives you a function whose identity never changes across renders but whose body always sees the latest state and props. Both halves of the fork, no trade-off.

This post covers the API, the three-line implementation trick that makes it work, how it compares to useCallback and to React 19.2's built-in useEffectEvent, real patterns, and the one rule you must respect (don't call it during render). TypeScript-first.

The Problem in Thirty Seconds

Here's the bug factory. A chat component sends a heartbeat with the current draft text:

function Composer({ roomId }: { roomId: string }) {
  const [draft, setDraft] = useState('');

  useEffect(() => {
    const id = setInterval(() => {
      sendHeartbeat(roomId, draft); // ⚠️ which draft?
    }, 3000);
    return () => clearInterval(id);
  }, [roomId]); // draft intentionally omitted — we don't want to reset the timer

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

The interval closes over the draft that existed when the effect ran — the empty string. Every heartbeat sends '' forever. Add draft to the dependency array and the closure is fresh, but now the interval tears down and restarts on every keystroke. useCallback doesn't help: it has the exact same dependency array, so it forces the exact same choice — stale values or churning identity.

What you actually want is a function that is one stable thing over the component's lifetime, but reads current values whenever it fires. That's useEvent:

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

function Composer({ roomId }: { roomId: string }) {
  const [draft, setDraft] = useState('');

  const beat = useEvent(() => {
    sendHeartbeat(roomId, draft); // ✅ always the latest draft and roomId
  });

  useEffect(() => {
    const id = setInterval(beat, 3000);
    return () => clearInterval(id);
  }, [beat]); // beat never changes — effect runs once

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

beat is referentially identical on every render, so the effect runs once and the interval survives typing. When it fires, it reads draft through the latest render's closure. The dependency array is even honest — beat is listed, it just happens to be stable.

The Full API

There's almost nothing to learn:

const stableFn = useEvent(fn);

fn — any function. Arguments and return value pass straight through, this included.
stableFn — same TypeScript type as fn, but its identity is fixed for the lifetime of the component.

The typing is exact, not (...args: any[]) => any:

const format = useEvent((n: number, unit: string) => `${n}${unit}`);
format(3, 'px');   // ✅ string
format('3', 'px'); // ❌ type error

In development, passing a non-function logs useEvent expected parameter is a function, got … to the console instead of failing silently.

How It Works Inside

The entire implementation is short enough to read over coffee, and every line earns its place:

export const useEvent = <T extends Fn>(fn: T) => {
  const handlerRef = useRef(fn);

  useIsomorphicLayoutEffect(() => {
    handlerRef.current = fn;
  }, [fn]);

  return useCallback((...args) => {
    const fn = handlerRef.current;
    return fn(...args);
  }, []) as T;
};

Three details worth noticing:

A ref carries the latest closure. Each render produces a fresh fn closing over fresh state; the effect stashes it in handlerRef. The returned wrapper — memoized once with an empty dependency array — reads handlerRef.current at call time, not at render time. Stable shell, fresh core.
The ref updates in a layout effect, not a passive effect. useIsomorphicLayoutEffect runs synchronously after DOM mutation, before the browser paints and before passive useEffect callbacks. If the ref were updated in a plain useEffect, any event that fired in the gap — or any other effect running earlier in the same commit — could call the wrapper and hit the previous render's closure. The layout timing closes that window.
Isomorphic means SSR-safe. useLayoutEffect on the server prints a hydration warning; useIsomorphicLayoutEffect swaps in useEffect during SSR and the real thing in the browser. No warnings, no special-casing in your code.

If this ref-holding trick sounds familiar, it's the same idea as useLatest — useEvent is essentially useLatest plus a stable callable wrapper. Reach for useLatest when you want to read a fresh value inside some existing callback; reach for useEvent when the callback itself is the thing you're passing around.

useEvent vs useCallback

They solve different problems, and the comparison makes both clearer:

	`useCallback`	`useEvent`
Identity	Changes whenever deps change	Never changes
Closure freshness	Only as fresh as your dep array is correct	Always latest — read at call time
Dependency array	Required; the bug surface	None
Callable during render?	✅ Yes	❌ No — event/effect time only
Best for	Values computed during render (memoized selectors, render props)	Handlers fired later (events, timers, subscriptions)

The render-time row is the real dividing line. useCallback's result is an ordinary value — you can call it while rendering to compute JSX. useEvent's wrapper reads a ref that is only guaranteed current after commit, so calling it during render can observe a previous render's state (and breaks the concurrent-rendering contract the RFC was careful about). The rule of thumb writes itself: if the function fires in response to something — a click, a tick, a message — use useEvent. If it computes something during render, use useCallback.

useEvent vs React's useEffectEvent

The 2022 RFC was ultimately superseded: React shipped the idea as useEffectEvent, stable since React 19.2. If you're on 19.2+ you should know how the two relate:

useEffectEvent is deliberately narrower. The returned function may only be called from inside effects (the ESLint rule enforces it), and must not be passed to other components or hooks. React's team scoped it to the one pattern they considered airtight: reading fresh values from an effect without re-triggering it.
useEvent covers the wider surface. Passing a stable handler to a memoized child, an imperative widget, a WebSocket wrapper, or a third-party SDK — all things useEffectEvent's linter will reject — are precisely what a userland useEvent is for. The trade-off is that the wider surface includes the render-time foot-gun above, and you hold the discipline instead of the linter.
They coexist fine. Use useEffectEvent inside effects on React 19.2+, and useEvent for stable identity across component boundaries — or use useEvent everywhere below 19.2, where useEffectEvent doesn't exist.

Patterns

A Handler Prop That Doesn't Break React.memo

The classic list-row scenario — a memoized row re-renders anyway because the parent recreates onSelect each render:

const Row = React.memo(function Row({ item, onSelect }: RowProps) {
  return (
    <li onClick={() => onSelect(item.id)} className="row">
      {item.label}
    </li>
  );
});

function List({ items }: { items: Item[] }) {
  const [selected, setSelected] = useState<string[]>([]);

  const handleSelect = useEvent((id: string) => {
    // reads latest `selected`, no dep array to maintain
    setSelected(selected.includes(id)
      ? selected.filter(s => s !== id)
      : [...selected, id]);
  });

  return (
    <ul>
      {items.map(item => (
        <Row key={item.id} item={item} onSelect={handleSelect} />
      ))}
    </ul>
  );
}

handleSelect is the same reference on every render, so React.memo actually memoizes. With useCallback you'd either list selected (identity churns, memo defeated) or use the functional-update form everywhere (fine here, impossible once the handler reads two pieces of state).

Subscriptions That Never Re-Subscribe

WebSockets, EventSource, SDKs — anywhere tearing down a connection just because a closure went stale is embarrassing:

function usePriceFeed(symbol: string, threshold: number) {
  const [price, setPrice] = useState(0);

  const onMessage = useEvent((e: MessageEvent) => {
    const next = JSON.parse(e.data).price as number;
    setPrice(next);
    if (next > threshold) notify(symbol, next); // latest threshold, always
  });

  useEffect(() => {
    const ws = new WebSocket(`wss://feed.example.com/${symbol}`);
    ws.addEventListener('message', onMessage);
    return () => ws.close();
  }, [symbol, onMessage]); // reconnects only when symbol changes

  return price;
}

The socket reconnects when symbol changes — a real reason — and never when threshold does. Note that for plain DOM targets, useEventListener already does this internally (it wraps your handler in useLatest), so you only need useEvent when you own the subscription plumbing.

Timers — or Just Use the Library's

The heartbeat example above is common enough that @reactuses/core ships it solved: useInterval keeps your callback fresh without restarting the timer — and its own implementation is built on useEvent and useLatest. Same story for useTimeout, useDebounceFn, and useThrottleFn: the stale-closure protection is baked in, so check whether the hook you're about to build already exists before wiring useEvent yourself.

Stable Callbacks for Imperative Widgets

Chart libraries, map SDKs, and editors typically take handlers at construction time:

function Editor({ docId }: { docId: string }) {
  const [dirty, setDirty] = useState(false);

  const handleSave = useEvent((content: string) => {
    saveDocument(docId, content); // latest docId
    setDirty(false);
  });

  useEffect(() => {
    const editor = createEditor('#mount', { onSave: handleSave });
    return () => editor.destroy();
  }, [handleSave]); // stable → editor created exactly once

  return <div id="mount" data-dirty={dirty} />;
}

Recreating a heavyweight editor because docId changed identity in a closure is exactly the kind of waste useEvent deletes.

The Rules

Two, and they're both consequences of the ref timing:

Don't call the returned function during render. It's for event handlers, effects, timers, callbacks — things that fire after commit. During render, the ref may still point at the previous closure.
Don't use it to lie to yourself about effects. If an effect genuinely should re-run when a value changes (a query refetch when filters change, say), wrapping the logic in useEvent to silence the linter buries a real dependency. useEvent is for "read the latest, don't re-fire"; it's not a universal dependency-array mute button.

Takeaways

useEvent returns a function with permanent identity and an always-fresh closure — the two things useCallback makes you choose between.
The trick is a ref updated in a layout effect plus a once-memoized wrapper that reads the ref at call time. useIsomorphicLayoutEffect keeps it SSR-safe.
useCallback for render-time values, useEvent for fired handlers. Never call a useEvent function during render.
On React 19.2+, useEffectEvent covers the inside-an-effect case with linter enforcement; useEvent covers stable handlers passed across component and library boundaries.
Check the library first — useEventListener, useInterval, useDebounceFn and friends already ship with stale-closure protection built in.

Grab it from @reactuses/core and retire the dependency-array whack-a-mole.

DEV Community: ReactUse

React useTimeout Hook: Declarative setTimeout with Cleanup (2026)

Quick Start

Two Hooks, One Engine

What It Actually Does

The Patterns Worth Copying

The delayed spinner

Auto-dismiss with hover-to-pause

A cooldown button

Yielding to the browser

Gotchas Worth Knowing

When Not to Use It

Takeaways

React useEventListener Hook: Type-Safe DOM Events (2026)

Quick Start

What It Actually Does

The Four Ways to Name a Target

What TypeScript Actually Infers

Patterns

Keyboard shortcuts

Non-passive wheel and touch listeners

Window and document events React doesn't give you props for

Rate-limiting a hot event

Gotchas Worth Knowing

When Not to Use It

Takeaways

React useScrollLock Hook: Lock Body Scroll for Modals (2026)

Quick Start

What useScrollLock Actually Does

Why overflow: hidden Isn't Enough on iOS

useScrollLock vs the Other Four Approaches

Patterns

1. Declare the lock, don't toggle it

2. Lock a scroll container, not the document

3. Lock during a drag

Gotchas Worth Knowing

1. The lock is a style, not a lifecycle

2. One owner per element

3. initialState: true skips the iOS guard

4. Desktop layout shift

5. Pass a getter, not document.body, for SSR

6. hidden stops gestures, not programmatic scrolling

When Not to Use useScrollLock

Takeaways

React scrollIntoView with useRef: Scroll to an Element (2026)

The Arguments You Actually Have

Sticky Headers: Use CSS, Not a Magic Number

Scrolling to Something That Just Rendered

Where the Native Call Runs Out

useScrollIntoView

Cancelable is the one you'll actually feel

Reduced motion is handled

Scrolling inside a container, and sideways

Scroll to the first invalid field

Gotchas Worth Knowing

When to Skip the Hook

Takeaways

React useSessionStorage Hook: Per-Tab State That Survives Reloads (2026)

Quick Start

What sessionStorage Actually Promises

useSessionStorage vs useLocalStorage vs useCookie vs useState

What You Get Over the Hand-Rolled Version

Patterns

Multi-step forms and wizards

Surviving a redirect round-trip

Per-tab view state that must not sync

Once per session

A stable per-tab ID

Gotchas Worth Knowing

When Not to Use useSessionStorage

Takeaways

React useLatest Hook: Read Fresh State in Async Callbacks (2026)

Quick Start

What useLatest Actually Is

useLatest vs useRef vs useState

useLatest vs useEvent vs useEffectEvent

Patterns

After an await

Subscriptions you create once

Timers

Why `overflow: hidden` Isn't Enough on iOS

3. `initialState: true` skips the iOS guard

5. Pass a getter, not `document.body`, for SSR

6. `hidden` stops gestures, not programmatic scrolling

After an `await`

Pausing: `null` vs. `pause()` / `resume()`

`immediate`: Fire Now, Then Every N ms

Press `/` to search