DEV Community: ReactUse

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.

Barrel Files: Why index.ts Re-Exports Hurt Tree Shaking, Next.js Dev Memory, and tsc (2026)

ReactUse — Thu, 06 Aug 2026 01:30:20 +0000

A barrel file is an index.ts whose only job is to re-export other modules, so consumers can write one tidy import instead of five. Almost every TypeScript codebase has them; almost every npm library ships one as its entry point. They look like free organization — and for years the ecosystem treated them that way.

They are not free. Barrel files are quietly behind three of the most common performance complaints in modern React development: bundles that don't tree-shake the way you expect, Next.js dev servers and tsc runs that get slower and hungrier as the app grows, and circular-dependency bugs that surface as Cannot access 'X' before initialization. We maintain @reactuses/core, a library of 120+ React hooks behind exactly one such barrel, and we recently had to rebuild our entire dist layout because of it — a Next.js dev page importing a single hook was pulling a 552 kB client chunk that dropped to 64 kB once the barrel was fixed. This post explains the mechanics behind all three problems and what to do about them, from both sides of the node_modules boundary.

What Is a Barrel File?

A barrel file gathers a directory's public surface into one module:

// src/hooks/index.ts — the "barrel"
export * from './useAuth';
export * from './useCart';
export * from './useCheckout';
export * from './useAnalytics';
// …forty more

Consumers then import from the directory instead of the file:

import { useAuth } from '@/hooks';        // via the barrel
// instead of
import { useAuth } from '@/hooks/useAuth'; // direct

Published libraries do the same thing at package scale: the main/exports entry of react-use, lodash-es, @mui/material, date-fns — and yes, @reactuses/core — is a barrel that re-exports every public module. One import specifier, one autocomplete namespace, one place to define the public API. That's the appeal.

The cost comes from a fact that's easy to forget: a module import is not a symbol lookup, it's a graph traversal. When any runtime or tool — a bundler, Node, tsc, the TS language server — resolves import { useAuth } from '@/hooks', it must load the barrel, and the barrel's body says "evaluate all forty-four of my children." The import of one symbol has become an import of everything, and everything those things import, transitively. Every problem in this post is that one sentence wearing a different costume.

Harm #1: Tree Shaking Becomes Fragile (or Silently Impossible)

Tree shaking is dead-code elimination driven by the static structure of ES modules: the bundler builds the full module graph, marks which exports are actually used, and drops the rest. In theory a barrel is transparent to this — export * is statically analyzable, and a good bundler can trace useAuth through the barrel to its home module and discard the siblings.

In practice, the theory has conditions, and barrels are where they go to die:

Side effects poison the whole barrel. A bundler may only drop a module if doing so is unobservable. If one module in the barrel runs top-level code — patches a global, registers a custom element, calls injectGlobalStyles(), even constructs a Map the bundler can't prove pure — the bundler must keep it, along with anything it imports. The sideEffects: false field in package.json is the library author's promise that lets bundlers skip this analysis; forget it (or set it wrong) and a 200-module barrel is bundled pessimistically. One misbehaving module taxes every consumer of every other module, because the barrel wired their fates together.

CommonJS output turns the shaking off entirely. Tree shaking needs ESM's static import/export. If your package's entry resolves to CJS (an old main field, a misconfigured exports map, a tool that transpiled your ESM to require calls), the bundler sees dynamic property access on module.exports and keeps everything. A CJS barrel of 120 hooks is your bundle, whatever you imported.

Transpiler artifacts defeat purity analysis. Class fields, decorators, and enums often compile to top-level IIFEs and assignments that look side-effectful. Without /*#__PURE__*/ annotations, the bundler keeps them — and in a barrel, "them" means every module in the graph, not just the one you imported.

And in dev mode, none of this runs anyway. This is the part that surprises people: tree shaking is a production optimization. Dev servers — webpack in dev, Next.js dev, Vite's on-demand transform of a pre-bundled dependency — do not shake. They resolve and execute the graph as written. Importing one hook through a barrel in dev means loading, transforming, and evaluating the entire library, every cold start, on every page that touches it. Which brings us to the second harm.

Harm #2: Next.js Dev and tsc Pay the Full Graph, in Time and Memory

Here is the measurement that forced our rebuild. A Next.js App Router page in dev mode, importing exactly one hook:

'use client';
import { useDebounce } from '@reactuses/core';

The dev-mode client chunk for that page: 552 kB. Not because useDebounce is big — it's a few hundred bytes around a setTimeout — but because the package entry was a barrel and dev mode doesn't shake, so the page compiled and shipped all 120+ hooks, including the heavyweight ones that drag in QR-code generation and file-saving dependencies the page never referenced.

Multiply this pattern across a real app — a few component libraries, an icon package, a date library, your own @/components and @/utils barrels — and you get the familiar symptoms that people rarely attribute to their imports:

Slow cold compiles and route transitions in dev. Next.js compiles pages on demand; every barrel in a page's import graph multiplies the number of modules to resolve, transform, and cache. Thousands of extra modules per page is common. The webpack-based dev server also holds all of these module records, transformed source, and source maps in memory — this is a big slice of the multi-gigabyte next dev processes people complain about, and why memory climbs as you visit more routes.
tsc time and memory scale with the graph, not your code. The type checker must load, bind, and check every file reachable from your entry points. Barrels make everything reachable. A type-only reference to one hook still parses 120 modules and their .d.ts dependency chains. The same applies to the TS language server in your editor — the "why does VS Code need 4 GB for this project" problem is very often a module-graph problem, and barrels are the graph's fan-out points.
Test startup pays it too. Jest and Vitest resolve imports per test file. A unit test importing one helper through a barrel evaluates the whole barrel — a classic reason trivial test suites take seconds per file to boot.

`optimizePackageImports` — and the catch we hit

Next.js ships a direct countermeasure: optimizePackageImports. Listing a package there makes the compiler rewrite barrel imports into direct per-module imports at build time:

// you write
import { useDebounce } from '@reactuses/core';
// the compiler resolves through the barrel and emits (conceptually)
import { useDebounce } from '@reactuses/core/dist/useDebounce/index.mjs';

Best of both: ergonomic imports in source, no barrel traversal in the compiled graph. Many popular libraries (lucide-react, @mui/icons-material, date-fns, …) are on the default list.

But there's a precondition the docs understate, and it's the one that bit us: the optimizer can only unroll a barrel into files that actually exist. It works by statically analyzing the package's entry and mapping each named export to the real module file that defines it. Until recently, @reactuses/core's published dist was one inlined bundle — our source had per-hook files, but the build tool (bunchee) compiled the whole library into a single index.mjs. From the optimizer's perspective every export was defined in the entry itself. There was nothing to unroll, no matter what the consumer configured. A barrel is only optimizable if it's a thin barrel — pure re-exports over real per-module files — all the way into dist.

Harm #3: Barrels Breed Circular Dependencies

The third cost isn't performance, it's correctness. Barrel files are the single most common way import cycles enter a codebase, because they add a hidden edge to every import that goes through them.

The trap looks like this:

// hooks/index.ts
export * from './useAuth';
export * from './useCart';

// hooks/useCart.ts — author wants useAuth, imports it "the tidy way"
import { useAuth } from '.';   // ← through the barrel, not './useAuth'

export function useCart() { const user = useAuth(); /* … */ }

The cycle is now index.ts → useCart.ts → index.ts. The author never wrote "useCart depends on the whole hooks directory," but that's what the import says — and every future module added to the barrel silently joins useCart's dependency graph, and vice versa. Auto-import makes this worse: editors happily complete from the barrel, so cycles accrete without anyone choosing them.

Sometimes the cycle is harmless and you never notice. Whether it bites depends on evaluation order — which module the runtime happens to start evaluating first — and that's exactly the kind of thing that differs between your bundler, Node, and Jest:

ESM: imports are hoisted live bindings, so mutually recursive functions work — but a const/arrow-function export read during the cycle throws the infamous ReferenceError: Cannot access 'useAuth' before initialization (temporal dead zone). Typically it appears only in one tool ("works in Vite, dies in Jest") because evaluation order differs.
CJS: no TDZ, something worse — the partially-initialized exports object. Mid-cycle imports are silently undefined, and you get TypeError: useAuth is not a function at call time, far from the actual cause, or extends undefined for classes.

Cycles also degrade tooling quietly: bundlers can't code-split modules locked in a cycle (they must land in the same chunk), and HMR invalidation spreads through cycle members, making dev updates slower. The graph problem and the correctness problem are the same problem.

What To Do Instead

In application code

Import from the module, not the barrel, inside the same package. The rule that prevents both the graph blowup and the cycles: barrels are for external consumers; internal code imports siblings directly (./useAuth, not .). Lint it: import/no-cycle catches the cycles (worth its cost in CI), and eslint-plugin-no-barrel-files / import/no-internal-modules can enforce a policy either way.
Question each barrel's existence. A barrel that groups five cohesive files is fine. App-wide components/index.ts with 300 exports is a bomb wired to every page. If a barrel exists only so imports "look clean," TypeScript path aliases (@/components/Button) give you short imports with none of the graph cost.
In Next.js, list heavy barrel packages in optimizePackageImports — and verify it worked by checking the dev chunk size, because (as above) not every package ships an optimizable dist.

As a library author

This is our side of the fence, and what #216 changed in @reactuses/core:

Ship per-module files, not an inlined bundle. In Rollup terms preserveModules; in tsdown it's one flag. Our whole config:

   // tsdown.config.ts
   import { defineConfig } from 'tsdown';

   export default defineConfig({
     entry: ['src/index.ts', 'src/useQRCode/index.ts'],
     format: ['esm', 'cjs'],
     dts: true,
     unbundle: true,   // one output file per module — the entry stays a real barrel
     target: 'es2015',
     platform: 'neutral',
   });

dist now mirrors src: dist/useDebounce/index.mjs, dist/useLocalStorage/index.mjs, …, with dist/index.mjs a genuinely thin barrel of re-exports. (We switched tools to get this: bunchee couldn't emit unbundled output, and OOM'd when we tried to fake it with 120 separate entry points.)

Declare sideEffects: false in package.json — true for a hooks library, and the single highest-leverage line for your consumers' bundles.
Add a subpath wildcard to exports, so consumers who want to bypass the barrel entirely can:

   "./*": {
     "import": { "types": "./dist/*/index.d.mts", "default": "./dist/*/index.mjs" },
     "require": { "types": "./dist/*/index.d.ts", "default": "./dist/*/index.js" }
   }

Which enables the zero-barrel import form: import { useDebounce } from '@reactuses/core/useDebounce'.

The result: the same Next.js dev page importing useDebounce went from a 552 kB chunk (every hook, because the barrel was an inlined bundle) to 64 kB (useDebounce and its actual dependency chain) — an 88% cut, with no change to the consumer's code. optimizePackageImports finally had files to point at.

Takeaways

A barrel file converts "import one thing" into "traverse everything." That's its entire cost model; every symptom follows.
Tree shaking can see through barrels, but only if every module is side-effect-clean, ESM, and sideEffects is declared — and it never runs in dev, where you pay the full graph in compile time and memory (Next.js dev, tsc, TS server, Jest alike).
Never import through your own barrel from inside the package — that's how cycles start, and cycles are why you see Cannot access 'X' before initialization in one tool but not another.
Library authors: thin barrel over per-module dist files, sideEffects: false, subpath exports. That combination is what makes consumers' optimizers (like optimizePackageImports) actually work — an inlined single-file dist defeats them even when your source layout is perfect.

@reactuses/core ships 120+ SSR-safe, TypeScript-first hooks — since v6.5.0 with per-module dist, so you get useDebounce without paying for the other 119. Browse them at reactuse.com.

React useMeasure Hook: Measure DOM Elements with ResizeObserver (2026)

ReactUse — Wed, 05 Aug 2026 02:53:06 +0000

Sooner or later every React app needs to know how big an element is. A chart needs its container's pixel width before it can draw. A virtualized list needs row heights. An auto-growing textarea, a truncation detector, a component that switches layout when it — not the viewport — gets narrow: all of them need live element dimensions, and React doesn't provide them. So you reach for getBoundingClientRect() in an effect, discover it only runs once, add a resize listener on window, and then notice the element also resizes when a sibling collapses, a font loads, or content changes — none of which fire a window resize event.

The correct primitive is ResizeObserver, and useMeasure from @reactuses/core is that primitive wrapped into one line: pass a ref, get back a live rect. No observer construction, no disconnect bookkeeping, no stale-closure traps. This post walks the API, the contentRect gotcha that trips almost everyone, how the hook works inside, how it compares to its sibling hooks (useElementSize, useElementBounding, useResizeObserver), and migration from react-use-measure. TypeScript-first.

The Simplest Case: A Live-Sized Container

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

function Chart() {
  const ref = useRef<HTMLDivElement>(null);
  const [rect] = useMeasure(ref);

  return (
    <div ref={ref} style={{ width: '100%', height: '400px' }}>
      <svg width={rect.width} height={rect.height}>
        {/* draw with real pixel dimensions */}
      </svg>
    </div>
  );
}

That's the whole pattern: a ref on the element, useMeasure(ref), and a rect that re-renders the component whenever the element's content box changes size — window resizes, flexbox reflows, sidebar toggles, font swaps, anything. You never touch ResizeObserver directly and there's no cleanup to remember; the observer disconnects automatically on unmount.

The Full API

const [rect, stop] = useMeasure(target, options?);

target accepts the same flexible shapes as every element hook in @reactuses/core:

useMeasure(ref);                          // a React ref object
useMeasure(document.querySelector('#el')); // a raw Element
useMeasure(() => document.body);           // a function returning an element

options is a standard ResizeObserverOptions object — { box: 'content-box' | 'border-box' | 'device-pixel-content-box' } — controlling which box triggers observations.

rect is a UseMeasureRect:

type UseMeasureRect = {
  x: number;
  y: number;
  width: number;
  height: number;
  top: number;
  left: number;
  bottom: number;
  right: number;
};

Before the first observation fires (including during SSR), every field is 0.

stop is a function that disconnects the observer. Call it when you've measured what you needed and don't want further re-renders — say, after capturing an initial layout for an animation:

const [rect, stop] = useMeasure(ref);

useEffect(() => {
  if (rect.width > 0) {
    startEnterAnimation(rect);
    stop(); // one measurement was enough
  }
}, [rect, stop]);

The contentRect Gotcha: top/left Are Not Viewport Coordinates

This is the number-one confusion with every ResizeObserver-based measure hook, so let's kill it early. The rect comes from entry.contentRect, and contentRect is relative to the element's own box, not the viewport:

width / height — the content box size: excludes padding, border, and scrollbars.
top / left (and x / y) — the offset of the content box from the element's border box. In practice: your padding-top and padding-left, not the element's position on the page.

So for an element with padding: 16px sitting 300px down the page, useMeasure reports top: 16, not top: 300. If what you actually want is where the element is on screen — for positioning a tooltip, a dropdown, a spotlight overlay — you want getBoundingClientRect() semantics, and that's a different hook: useElementBounding, which returns viewport-relative coordinates and also updates on scroll.

Rule of thumb: useMeasure answers "how big is it?"; useElementBounding answers "where is it?"

How It Works Inside

useMeasure is a thin layer over the library's useResizeObserver hook:

import { useState } from 'react';
import { useResizeObserver } from '../useResizeObserver';

export const useMeasure = (target, options = defaultOptions) => {
  const [rect, setRect] = useState(defaultState); // all zeros

  const stop = useResizeObserver(
    target,
    entries => {
      if (entries[0]) {
        const { x, y, width, height, top, left, bottom, right }
          = entries[0].contentRect;
        setRect({ x, y, width, height, top, left, bottom, right });
      }
    },
    options,
  );

  return [rect, stop] as const;
};

The interesting machinery lives in useResizeObserver:

export const useResizeObserver = (target, callback, options) => {
  const savedCallback = useLatest(callback);
  const observerRef = useRef<ResizeObserver>();
  const { key: targetKey, ref: targetRef } = useStableTarget(target);

  const stop = useCallback(() => {
    observerRef.current?.disconnect();
  }, []);

  useDeepCompareEffect(() => {
    const element = getTargetElement(targetRef.current);
    if (!element) return;
    observerRef.current = new ResizeObserver(savedCallback.current);
    observerRef.current.observe(element, options);
    return stop;
  }, [targetKey, options]);

  return stop;
};

Three details worth noticing:

useLatest wraps the callback — you can pass an inline arrow function without tearing down and recreating the observer on every render. The observer is constructed once; the ref always points at the latest callback.
useDeepCompareEffect guards the options object — useMeasure(ref, { box: 'border-box' }) passes a fresh object literal every render. A plain useEffect with [options] would disconnect and reconnect the observer each time. Deep comparison means the observer only rebuilds when the options values actually change.
The observer is created inside an effect — effects don't run on the server, so new ResizeObserver(...) never executes during SSR. The hook is SSR-safe by construction: the server renders with the all-zeros rect, the client hydrates identically, and the first observation fires after mount.

That third point also explains the initial { width: 0, height: 0 } render. Guard against it when zero would break your math:

const [rect] = useMeasure(ref);

return (
  <div ref={ref}>
    {rect.width > 0 && <Chart width={rect.width} height={rect.height} />}
  </div>
);

useMeasure vs useElementSize vs useElementBounding vs useResizeObserver

@reactuses/core ships four hooks in this space. They're layered, not redundant:

	`useMeasure`	`useElementSize`	`useElementBounding`	`useResizeObserver`
Returns	`[rect, stop]` — full 8-field rect	`[width, height]`	`{ x, y, top, left, ... }` viewport-relative	`stop` (you get raw entries in a callback)
Source	`contentRect`	`contentBoxSize` / `borderBoxSize`	`getBoundingClientRect()`	Raw `ResizeObserverEntry[]`
Coordinates	Element-relative (padding offsets)	— (size only)	Viewport-relative	Whatever you read from entries
Updates on scroll	No	No	Yes (window scroll + resize listeners)	No
Box option	Observation trigger only	Measured value follows `box`	—	Observation trigger only
Best for	Size + a stop switch	Just width/height, minimal re-renders	Tooltips, popovers, overlays — positioning	Custom logic; multiple elements; no state updates

Two distinctions deserve a sentence each:

useElementSize respects the box option in the measured value. With { box: 'border-box' } it reports borderBoxSize — padding and border included — which is what you usually mean by "how big is this element". useMeasure always reports the content box regardless of which box triggers observation, because contentRect is all ResizeObserver entries expose rect-wise.
useElementBounding is the only one that tracks position on scroll. It observes with ResizeObserver and listens to window scroll / resize (passive), recomputing getBoundingClientRect() on each. Heavier, but correct for anything anchored to screen position.

If you just need the viewport size, skip element observation entirely — that's useWindowSize.

Patterns

Container-Query-Style Responsive Component

Media queries respond to the viewport; components live in containers. A card in a wide main column and the same card in a narrow sidebar should lay out differently even on the same screen:

function ProfileCard() {
  const ref = useRef<HTMLDivElement>(null);
  const [rect] = useMeasure(ref);
  const compact = rect.width > 0 && rect.width < 320;

  return (
    <div ref={ref} className={compact ? 'card card--stacked' : 'card card--row'}>
      <Avatar />
      <Bio truncated={compact} />
    </div>
  );
}

The component adapts to the space it's given, wherever it's mounted. (CSS container queries cover the styling half of this; useMeasure covers the half where JavaScript needs the number — chart scales, virtualization math, conditional rendering.)

Canvas / SVG That Fills Its Parent

Canvas and SVG need explicit pixel dimensions. Bind them to the measured parent and redraw on change:

function Sparkline({ data }: { data: number[] }) {
  const wrapRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const [rect] = useMeasure(wrapRef);

  useEffect(() => {
    const canvas = canvasRef.current;
    if (!canvas || rect.width === 0) return;
    canvas.width = rect.width * devicePixelRatio;
    canvas.height = rect.height * devicePixelRatio;
    drawSparkline(canvas, data);
  }, [rect, data]);

  return (
    <div ref={wrapRef} className="sparkline-wrap">
      <canvas ref={canvasRef} style={{ width: '100%', height: '100%' }} />
    </div>
  );
}

Every layout change — panel resize, sidebar collapse, orientation flip — re-renders the canvas at the correct resolution. No window.resize listener, which would miss the panel-resize and sidebar cases entirely.

Auto-Height Animation (Measure, Then Animate)

CSS can't transition height: auto. Measure the content, animate to the number:

function Collapsible({ open, children }: Props) {
  const innerRef = useRef<HTMLDivElement>(null);
  const [rect] = useMeasure(innerRef);

  return (
    <div
      style={{
        height: open ? rect.height : 0,
        overflow: 'hidden',
        transition: 'height 200ms ease',
      }}
    >
      <div ref={innerRef}>{children}</div>
    </div>
  );
}

Because the measurement is live, the panel stays correct even if its content changes while open — an image finishes loading, a nested section expands. A one-shot getBoundingClientRect() snapshot would go stale the moment content shifted.

Truncation Detection

Show a "read more" affordance only when text actually overflows:

function Excerpt({ text }: { text: string }) {
  const ref = useRef<HTMLParagraphElement>(null);
  const [rect] = useMeasure(ref);
  const truncated =
    ref.current != null && ref.current.scrollHeight > Math.ceil(rect.height);

  return (
    <>
      <p ref={ref} className="clamp-3">{text}</p>
      {truncated && <button>Read more</button>}
    </>
  );
}

rect.height is the visible (clamped) content height, scrollHeight the full content height; comparing them detects overflow — and keeps detecting it as the container resizes, which is exactly when truncation state flips.

Coming from react-use-measure

If you've used pmndrs' react-use-measure, the mental model transfers directly — with a few differences:

// react-use-measure — hook creates the ref for you
const [ref, bounds] = useMeasure();
<div ref={ref} />

// @reactuses/core — you own the ref (or pass an element/function)
const ref = useRef<HTMLDivElement>(null);
const [rect, stop] = useMeasure(ref);
<div ref={ref} />

Ref ownership: react-use-measure returns a callback ref; @reactuses/core accepts your ref, a raw element, or a getter function. Owning the ref means you can share it with other hooks (useClickOutside, useHover) on the same element without ref-merging utilities.
Coordinates: react-use-measure reports viewport-relative bounds (with an optional scroll option); @reactuses/core's useMeasure reports contentRect. For viewport-relative-plus-scroll behavior, use useElementBounding — that's the true equivalent.
Debounce: react-use-measure takes a debounce option. Here you compose instead: pipe the rect through useDebounce if you need to throttle downstream work.
Stop switch: only @reactuses/core gives you stop — a clean way to end observation after you've got what you came for.
One library, 100+ hooks: you're pulling from a full collection rather than adding a single-purpose dependency.

Takeaways

useMeasure gives you a live element rect with one line — ResizeObserver underneath, zero observer bookkeeping, automatic cleanup.
It measures the content box, element-relative. top/left are padding offsets, not page position. For viewport coordinates and scroll tracking, use useElementBounding; for border-box sizes, useElementSize with { box: 'border-box' }.
The first render is all zeros — on the server and before the first observation. Guard rect.width > 0 where zero breaks your math.
Inline callbacks and fresh options objects are safe — useLatest and useDeepCompareEffect inside prevent observer churn.
stop ends observation on demand — measure once for an animation, then stop paying for re-renders.
SSR-safe by construction — the observer is created in an effect, which never runs on the server.

Grab it from @reactuses/core and stop hand-rolling ResizeObserver wiring.

React useDisclosure Hook: Manage Modal & Drawer State (2026)

ReactUse — Tue, 04 Aug 2026 07:51:51 +0000

Every React app accumulates toggleable UI — a confirmation dialog, a mobile nav drawer, a settings popover, a notification panel. The state behind each one is always the same: a boolean, a way to open, a way to close, and maybe a callback for analytics or focus management when the transition happens. So you write useState(false) and three inline handlers, copy-paste it to the next modal, and somewhere around the fifth disclosure widget you notice you've scattered the same five-line pattern across a dozen files with nothing reusable and no lifecycle hooks.

useDisclosure from @reactuses/core is that pattern extracted once: uncontrolled by default, controlled when you need it, with onOpen / onClose / onChange callbacks that fire at exactly the right time. The returned handlers are ref-stabilized so they never cause downstream re-renders. This post walks the API, the internals, the controlled-vs-uncontrolled contract, and real patterns for modals, drawers, and composed multi-disclosure UIs. TypeScript-first.

The Simplest Case: A Modal Toggle

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

function App() {
  const { isOpen, onOpen, onClose } = useDisclosure();

  return (
    <>
      <button onClick={onOpen}>Open settings</button>
      {isOpen && (
        <dialog open>
          <h2>Settings</h2>
          <p>Your settings panel content here.</p>
          <button onClick={onClose}>Close</button>
        </dialog>
      )}
    </>
  );
}

No useState, no inline () => setOpen(true) / () => setOpen(false), no naming decisions. The hook returns named functions whose intent is obvious in JSX — onOpen on the trigger, onClose on the dismiss button. It returns the same function identity on every render (ref-stabilized), so passing onClose to a memoized child component doesn't break React.memo.

The Full API

const {
  isOpen,       // boolean — current state
  onOpen,       // () => void — set to true
  onClose,      // () => void — set to false
  onOpenChange, // () => void — toggle
  isControlled, // boolean — true if you passed isOpen in props
} = useDisclosure({
  defaultOpen,  // boolean — initial state (uncontrolled mode only)
  isOpen,       // boolean — pass to enter controlled mode
  onOpen,       // () => void — fires after opening
  onClose,      // () => void — fires after closing
  onChange,     // (isOpen: boolean | undefined) => void — fires on any change
});

Every field is optional. Call useDisclosure() with no arguments and you get an uncontrolled toggle that starts closed.

Lifecycle Callbacks: When Opening and Closing Have Side Effects

A boolean toggle becomes insufficient the moment your modal does more than show and hide. Without useDisclosure — side effects tangled in JSX:

<button onClick={() => {
  setIsOpen(true);
  analytics.track('pricing_modal_opened');
  focusTrap.activate();
}}>
  View pricing
</button>

With useDisclosure, the side effects live in the hook call, co-located and centralized:

const { isOpen, onOpen, onClose } = useDisclosure({
  onOpen() {
    analytics.track('pricing_modal_opened');
    focusTrap.activate();
  },
  onClose() {
    analytics.track('pricing_modal_closed');
    focusTrap.deactivate();
  },
});

// JSX is now clean
<button onClick={onOpen}>View pricing</button>

The callbacks fire after the state updates. The callback props are wrapped in useLatest internally — meaning you can pass inline arrow functions without causing the returned onOpen / onClose to get new identities.

Controlled Mode: When the Parent Owns the State

Pass isOpen in props and the hook switches to controlled mode:

function ControlledDrawer({ isOpen, onToggle }: Props) {
  const disclosure = useDisclosure({
    isOpen,
    onOpen: onToggle,
    onClose: onToggle,
  });

  // disclosure.isControlled === true
  return (
    <aside className={disclosure.isOpen ? 'open' : ''}>
      <button onClick={disclosure.onClose}>×</button>
    </aside>
  );
}

In controlled mode, onOpen and onClose do not update internal state — the hook respects the prop as the source of truth. The boundary is clean: isOpen is undefined → uncontrolled. isOpen is a boolean → controlled.

onOpenChange: The Toggle Shorthand

onOpenChange acts as a toggle: calls onOpen when closed, onClose when open. Maps directly onto Radix-style single-callback APIs:

const { isOpen, onOpenChange } = useDisclosure();

<Dialog.Root open={isOpen} onOpenChange={onOpenChange}>
  <Dialog.Trigger>Open</Dialog.Trigger>
  <Dialog.Content>...</Dialog.Content>
</Dialog.Root>

How It Works Inside

Three building blocks:

useControlled — switches between internal useState and an external prop.
useLatest — wraps callback props in a ref so the returned handlers have stable identities.
The controlled guard — if (!isControlled) setIsOpen(...) ensures the hook never fights the parent.

No effects, no subscriptions, no browser APIs. SSR-safe by construction.

useDisclosure vs useBoolean vs useToggle

	useDisclosure	useBoolean	useToggle
Controlled mode	Yes	No	No
Lifecycle callbacks	`onOpen`, `onClose`, `onChange`	None	None
Stable handlers	Ref-stabilized	Standard `useCallback`	Standard `useCallback`
Best for	Modals, drawers, popovers	Simple show/hide flags	Minimal boolean toggle

Patterns

Confirmation Dialog

function DeleteButton({ onConfirm }: { onConfirm: () => void }) {
  const { isOpen, onOpen, onClose } = useDisclosure();

  return (
    <>
      <button onClick={onOpen}>Delete</button>
      {isOpen && (
        <div className="overlay" onClick={onClose}>
          <div className="dialog" onClick={e => e.stopPropagation()}>
            <p>Are you sure?</p>
            <button onClick={() => { onConfirm(); onClose(); }}>
              Yes, delete
            </button>
            <button onClick={onClose}>Cancel</button>
          </div>
        </div>
      )}
    </>
  );
}

Multiple Disclosures with Mutual Exclusion

function SettingsPanel() {
  const general = useDisclosure({ defaultOpen: true });
  const security = useDisclosure();
  const notifications = useDisclosure();

  const closeAll = () => {
    general.onClose();
    security.onClose();
    notifications.onClose();
  };

  const openExclusive = (target) => {
    closeAll();
    target.onOpen();
  };

  return (
    <div>
      <button onClick={() => openExclusive(general)}>General</button>
      <button onClick={() => openExclusive(security)}>Security</button>
      <button onClick={() => openExclusive(notifications)}>Notifications</button>

      {general.isOpen && <GeneralSettings />}
      {security.isOpen && <SecuritySettings />}
      {notifications.isOpen && <NotificationSettings />}
    </div>
  );
}

Accordion behavior without an accordion library.

Coming from Chakra UI

The API is nearly identical. Main differences:

No getButtonProps / getDisclosureProps — manages state, not DOM attributes.
onOpenChange instead of onToggle — matches Radix/Headless UI naming.
onChange callback for syncing to external stores.
No UI framework dependency.

Migration is a rename.

Takeaways

useDisclosure replaces useState(false) + three inline handlers across every modal, drawer, and popover.
Lifecycle callbacks centralize side effects — analytics, focus management, animation triggers.
Controlled mode is opt-in: pass isOpen and the hook defers to your state.
Handlers are ref-stabilized — safe to pass to memoized children.
onOpenChange is a toggle mapping onto Radix/Headless UI/Ariakit single-callback APIs.
SSR-safe by construction — pure React state.

Grab it from @reactuses/core and stop copy-pasting modal state.

React useInfiniteScroll Hook: Infinite Scrolling Made Simple (2026)

ReactUse — Mon, 03 Aug 2026 01:25:59 +0000

Every feed, every chat log, every search result page eventually asks the same question: how do I load more when the user reaches the bottom? The naive answer — a scroll listener, some arithmetic about scrollHeight and clientHeight, a boolean to prevent double-fetching — is maybe 30 lines, and every one of them is a trap. You forget to clean up the listener. You compare the wrong dimension. You fire the callback on mount before there's anything to scroll. You hard-code "bottom" and then product asks for a chat that loads history upward. You skip throttling and the callback fires 60 times while the user holds the scroll position at the threshold.

useInfiniteScroll from @reactuses/core replaces all of that with one call: point it at a scrollable element, give it a load-more function, and it handles the rest — arrival detection, direction, distance threshold, scroll-position preservation, and cleanup. This post walks the real implementation, the options that matter, and the patterns for feeds, chats, and horizontal carousels. TypeScript-first.

The Simplest Case: Load More at the Bottom

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

function Feed() {
  const containerRef = useRef<HTMLDivElement>(null);
  const [items, setItems] = useState<string[]>(() =>
    Array.from({ length: 20 }, (_, i) => `Item ${i + 1}`)
  );

  useInfiniteScroll(containerRef, async () => {
    const newItems = await fetchMoreItems(items.length);
    setItems(prev => [...prev, ...newItems]);
  });

  return (
    <div ref={containerRef} style={{ height: 400, overflow: 'auto' }}>
      {items.map(item => (
        <div key={item} style={{ padding: 16, borderBottom: '1px solid #eee' }}>
          {item}
        </div>
      ))}
    </div>
  );
}

That's it. Scroll to the bottom, fetchMoreItems fires. It doesn't fire again until the user scrolls away from the bottom and back. It doesn't fire during SSR. It cleans up the listener on unmount.

The Signature

useInfiniteScroll(target, onLoadMore, options?)

target — a ref to the scrollable DOM element (RefObject<Element>).
onLoadMore — a function (sync or async) called when the user reaches the scroll edge. It receives the full scroll state from useScroll: [x, y, isScrolling, arrivedState, directions].
options — everything useScroll accepts, plus three infinite-scroll-specific fields.

Options That Matter

`distance` — Fire Before the Edge

useInfiniteScroll(containerRef, loadMore, {
  distance: 200, // fire 200px before hitting the bottom
});

Default is 0. Set distance to preload: at 200, the next page starts fetching while there's still 200 px of content to scroll through.

`direction` — Not Just Bottom

useInfiniteScroll(containerRef, loadMore, {
  direction: 'top', // load older messages when scrolling up
});

Four directions: 'bottom' (default), 'top', 'left', 'right'. Chat apps want 'top' — the user scrolls up to load history. Horizontal carousels want 'left' or 'right'.

`preserveScrollPosition` — Stay Where You Were

useInfiniteScroll(containerRef, loadMore, {
  direction: 'top',
  preserveScrollPosition: true,
});

When loading content above the current viewport, the new items push everything down and the user loses their place. preserveScrollPosition: true fixes this: after onLoadMore resolves, the hook adjusts scrollTop by exactly the height of the newly inserted content.

Under the Hood

The implementation is 44 lines:

export const useInfiniteScroll = (target, onLoadMore, options = {}) => {
  const savedLoadMore = useLatest(onLoadMore);
  const direction = options.direction ?? 'bottom';
  const state = useScroll(target, {
    ...options,
    offset: {
      [direction]: options.distance ?? 0,
      ...options.offset,
    },
  });

  const di = state[3][direction]; // arrivedState[direction]

  useUpdateEffect(() => {
    const element = getTargetElement(target);
    const fn = async () => {
      const previous = {
        height: element?.scrollHeight ?? 0,
        width: element?.scrollWidth ?? 0,
      };
      await savedLoadMore.current(state);
      if (options.preserveScrollPosition && element) {
        element.scrollTo({
          top: element.scrollHeight - previous.height,
          left: element.scrollWidth - previous.width,
        });
      }
    };
    fn();
  }, [di, options.preserveScrollPosition, target]);
};

Three pieces make this work:

useScroll does the heavy lifting. It tracks scroll position, arrived state, and direction. The offset option shifts the arrival threshold — useInfiniteScroll maps distance to offset[direction].
useUpdateEffect prevents the mount-fire. It skips the first invocation and only fires when the arrived boolean actually changes.
useLatest kills stale closures. The callback always gets the latest version without recreating the scroll machinery.

Patterns

Chat History (Reverse Scroll)

function ChatHistory({ channelId }: { channelId: string }) {
  const ref = useRef<HTMLDivElement>(null);
  const [messages, setMessages] = useState<Message[]>([]);
  const [cursor, setCursor] = useState<string | null>(null);

  useInfiniteScroll(ref, async () => {
    const data = await fetchMessages(channelId, cursor);
    setMessages(prev => [...data.messages, ...prev]);
    setCursor(data.nextCursor);
  }, {
    direction: 'top',
    preserveScrollPosition: true,
    distance: 100,
  });

  return (
    <div ref={ref} style={{ height: 500, overflow: 'auto' }}>
      {messages.map(msg => <MessageBubble key={msg.id} message={msg} />)}
    </div>
  );
}

This is the pattern Slack, Discord, and every chat UI uses — and the one that's hardest to get right by hand.

Horizontal Carousel

function HorizontalGallery() {
  const ref = useRef<HTMLDivElement>(null);
  const [images, setImages] = useState<string[]>([]);

  useInfiniteScroll(ref, async () => {
    const moreImages = await fetchImages(images.length);
    setImages(prev => [...prev, ...moreImages]);
  }, {
    direction: 'right',
    distance: 200,
  });

  return (
    <div ref={ref} style={{ display: 'flex', overflowX: 'auto', gap: 16 }}>
      {images.map(src => <img key={src} src={src} style={{ width: 300 }} />)}
    </div>
  );
}

useInfiniteScroll vs. useIntersectionObserver

useIntersectionObserver watches a sentinel element. Works for any container including the window itself and handles complex layouts gracefully.
useInfiniteScroll watches the scroll position of a specific container. Simpler to wire up, handles all four directions natively, includes preserveScrollPosition out of the box.

Pick useInfiniteScroll for single-container setups. Pick useIntersectionObserver for window-level loading or complex nested scroll contexts.

SSR Safety

useInfiniteScroll creates no subscriptions during server rendering. useScroll guards on window existence. useUpdateEffect skips the first render entirely. SSR-safe by construction, like every hook in @reactuses/core.

Takeaways

One hook replaces the scroll listener, the math, and the cleanup.
distance preloads content so the user never waits at the bottom.
direction handles all four edges — feeds, chats, carousels.
preserveScrollPosition is the chat-history fix.
Built on useScroll — throttling, arrived-state tracking, and direction detection for free.
SSR-safe with nothing to configure.

Install @reactuses/core, point useInfiniteScroll at your list container, and stop writing scroll arithmetic by hand.

This post is part of the ReactUse hook guide series. The library ships 100+ hooks for browser APIs, state, effects, and elements — all SSR-safe, TypeScript-first, and tested.

React useThrottle Hook: Throttle Values & Callbacks (2026)

ReactUse — Fri, 31 Jul 2026 06:04:14 +0000

React useThrottle Hook: Throttle Values & Callbacks (2026)

A scroll listener fires at whatever rate the compositor feels like — often 60 times a second, sometimes 120. mousemove is worse. Feed either straight into setState and every wiggle of the wheel re-renders your component tree at frame rate; feed it into an analytics call or a network request and you've built a tiny DDoS against your own backend. Debouncing is the wrong fix here: a debounced scroll handler waits for the scrolling to stop, so your reading-progress bar freezes mid-scroll and jumps at the end. What you want is a steady cadence — run this at most once every N milliseconds, while the events keep coming. That's throttling.

useThrottle and useThrottleFn from @reactuses/core are that cadence as hooks — one for values, one for callbacks — built on lodash's battle-tested throttle and wrapped so the two classic React failure modes (stale closures, timers that outlive the component) can't happen. This post walks the real implementation, the leading/trailing knobs, the cancel/flush escape hatches, and one mount-timing subtlety the test suite pins down. TypeScript-first.

useThrottle — Throttle a Value

useThrottle takes a value that changes too fast and returns a copy that changes at a civilized pace:

import { useState } from 'react';
import { useThrottle } from '@reactuses/core';

function MarkdownEditor() {
  const [source, setSource] = useState('');
  const throttledSource = useThrottle(source, 500);

  return (
    <div className="editor">
      <textarea value={source} onChange={e => setSource(e.target.value)} />
      {/* re-parses at most twice per second, even while typing full speed */}
      <Preview markdown={throttledSource} />
    </div>
  );
}

The input stays perfectly responsive — source updates on every keystroke. Only the expensive consumer is throttled: throttledSource updates immediately on the first change, then at most once per 500 ms while changes keep arriving, and settles on the final value once they stop. Compare the debounced version of this editor: the preview would go blank-faced during typing and only catch up in the pauses. Throttle keeps it live, just at a lower refresh rate.

The signature:

function useThrottle<T>(value: T, wait?: number, options?: ThrottleSettings): T;

ThrottleSettings is lodash's — { leading?: boolean; trailing?: boolean } — and we'll get to it below.

useThrottleFn — Throttle a Callback

When the thing to slow down is a function rather than a value, useThrottleFn wraps it and hands back controls:

import { useState } from 'react';
import { useThrottleFn, useEventListener } from '@reactuses/core';

function ScrollSpy({ sectionIds }: { sectionIds: string[] }) {
  const [active, setActive] = useState(sectionIds[0]);

  const { run } = useThrottleFn(() => {
    setActive(computeActiveSection(sectionIds, window.scrollY));
  }, 200);

  useEventListener('scroll', run);

  return <TableOfContents ids={sectionIds} active={active} />;
}

The scroll event fires at frame rate; computeActiveSection runs five times a second. The return value is an object with three functions:

const { run, cancel, flush } = useThrottleFn(fn, wait, options);

run(...args) — the throttled function. Same parameters as fn, and it returns fn's result (the most recent one, when a call gets suppressed — standard lodash semantics).
cancel() — drop whatever trailing call is pending. A "Reset" button that clears the UI shouldn't be followed 200 ms later by a ghost update from the last scroll event; call cancel() when the interaction is abandoned.
flush() — the opposite: don't wait for the window to close, run the pending call now. Classic use: throttled autosave plus flush() on "Submit", so the final state is persisted before navigation, not 2 seconds after.

These aren't decorative — the library's test suite drives a full timeline through run/cancel/flush with fake timers and pins every intermediate count: the leading call fires synchronously, suppressed calls collapse into one trailing call carrying the latest arguments, cancel() really does drop the pending call, and flush() really does fire it early.

Under the Hood: lodash Plus Two Fixes

The implementation is short enough to read over coffee:

export function useThrottleFn<T extends (...args: any) => any>(
  fn: T, wait?: number, options?: ThrottleSettings,
) {
  const fnRef = useLatest(fn);

  const throttled = useMemo(
    () =>
      throttle(
        (...args: [...Parameters<T>]): ReturnType<T> => {
          return fnRef.current(...args);
        },
        wait,
        options,
      ),
    [wait, JSON.stringify(options)],
  );

  useUnmount(() => {
    throttled.cancel();
  });

  return { run: throttled, cancel: throttled.cancel, flush: throttled.flush };
}

The throttling engine is lodash-es's throttle — timing logic with a decade of production mileage, not a hand-rolled setTimeout dance. What the hook adds is exactly the two things that go wrong when you call lodash.throttle inside a component yourself:

No stale closures. The naive useMemo(() => throttle(fn, wait), []) freezes the first render's fn — with its first-render props and state — for the component's lifetime. Here the memoized throttle calls fnRef.current, a useLatest ref that re-points at the newest fn every render. Timing state lives in one stable throttle instance; the code it invokes is always current.
No timers outliving the component. useUnmount calls throttled.cancel(), so a pending trailing call can't fire into an unmounted component. The test suite asserts the timer count is literally zero after unmount.

One small delight in the deps array: JSON.stringify(options). You can pass { trailing: false } inline — a fresh object every render — without recreating the throttle instance, because the memo compares the options by content, not identity. And useThrottle itself is just this hook pointed at state — useThrottleFn(() => setThrottled(value), wait, options) with an effect calling run() whenever value changes. One timing engine, two shapes.

Tuning: leading and trailing

Both edges default to true, which is the behavior you usually want — instant first response, no lost final value:

useThrottle(value, 500);                      // fire now, then every ≤500ms, then final value
useThrottle(value, 500, { leading: false });  // skip the instant first update
useThrottle(value, 500, { trailing: false }); // skip the settle-to-final-value update

leading: false delays the first invocation to the end of the window. Useful when the first event of a burst isn't meaningful on its own — e.g. reporting "user is scrolling" analytics where you'd rather not fire on a single wheel tick.
trailing: false means calls made mid-window are dropped rather than deferred. Fine for continuous streams where the next window will bring a fresh reading anyway; wrong for anything where the last value matters (your progress bar would stop just short of 100%).
Both false is a lodash trap — the function can only fire if called when no window is open, which for a steady event stream means almost never. Don't.

The Mount Gotcha — the First Change Can Wait

Here's the subtlety worth knowing about useThrottle (the value version). Internally it calls run() in an effect on mount — that leading call just re-sets the initial value, invisible. But it also opens the throttle window. The consequence: a value change arriving within wait of mount doesn't update instantly, leading edge or no — it's mid-window, so it waits for the trailing edge. The test suite states it plainly:

const { result, rerender } = renderHook(props => useThrottle(props, 100), {
  initialProps: 0,
});
rerender(1);                     // change right after mount
jest.advanceTimersByTime(50);
expect(result.current).toBe(0);  // still the old value — deferred to t=100

After that first window expires, a change that arrives in quiet air gets its own leading edge and shows up immediately. So in steady state useThrottle feels instant-then-throttled, exactly as advertised — but if your component mounts and the value changes in the same breath (hydration handoffs, an immediate fetch result), that first change lands up to wait ms late. If that matters, shorten wait or throttle the source with useThrottleFn instead of the value.

Throttle or Debounce?

Thirty-second version, since they're the two ends of one spectrum:

Debounce = "wait for silence." Nothing happens until the events stop for wait ms. Right for search-as-you-type, autosave, resize-finished layout work — cases where only the final state matters. That's useDebounce / useDebounceFn.
Throttle = "steady heartbeat." Runs during the activity, at a capped rate. Right for scroll position, mouse tracking, drag feedback, progress reporting — cases where the user needs to see something happening while it happens.

The tell: if a debounced version of your feature feels frozen during interaction, you wanted throttle. The full decision guide with both hooks side by side is in Debounce vs Throttle in React.

The Rate-Limiting Family

useDebounce / useDebounceFn — the same value/callback pair, wait-for-silence timing, same lodash core and same stale-closure/unmount fixes.
useRafFn — throttling to the display's rhythm instead of a millisecond budget: runs a callback once per animation frame. For work that feeds rendering (element highlighting, canvas drawing), one-per-frame beats any hand-picked wait.
useRafState — useState whose setter commits on the next frame; multiple high-frequency sets per frame collapse into one render. The lightest-touch fix for mousemove-driven state.
useScroll and useMouse — position-tracking hooks you'll often find on the input side of a throttle.

SSR Safety

useThrottleFn creates the lodash throttle during render, but creating it starts no timers — timers start when run() is called, and every call site lives in an effect or an event handler, which never execute during server rendering. No window, no document, no clock touched on the server: your Next.js / Remix build renders the initial value and hydrates cleanly, and throttling wakes up with the client. SSR-safe by construction, like every hook in @reactuses/core.

Takeaways

Throttle is a cadence, debounce is a wait. For anything the user watches during the interaction — scroll, drag, mouse, live preview — reach for useThrottle / useThrottleFn, not debounce.
Values and callbacks are the same engine in two shapes: useThrottle is literally useThrottleFn pointed at a setState.
The wrapper earns its keep twice: useLatest kills stale closures, useUnmount cancels pending timers — the two bugs every hand-rolled lodash.throttle-in-React eventually ships.
cancel() and flush() are the escape hatches — drop the pending call when the interaction is abandoned, force it when the user commits.
Mind the mount window: a value change within wait of mount waits for the trailing edge — verified by the test suite, not vibes.
SSR-safe with nothing to configure — no timers, no browser globals until the client takes over.

Install @reactuses/core, point useThrottle at your noisiest value, and give your render loop a pulse instead of a seizure.

React useUpdateEffect Hook: Skip the First Render (2026)

ReactUse — Thu, 30 Jul 2026 02:09:09 +0000

React useUpdateEffect Hook: Skip the First Render (2026)

useEffect has no opinion about why it's running. Mount, update, doesn't matter — the callback fires either way. Which is how a "settings saved ✓" toast greets users the moment the page loads, an autosave POSTs a form nobody has touched yet, and an analytics event reports a "change" that was actually just the component appearing. What you meant was run this when the value changes; what you wrote was run this when the value changes, and also once at the start for no reason.

useUpdateEffect from @reactuses/core is useEffect minus the mount run: identical signature, identical cleanup semantics, skips exactly one invocation. The implementation is four lines, so this post covers what those four lines do, the one place the abstraction genuinely leaks — React 18 StrictMode, where we'll prove with a test that the callback does fire on mount in development — and the neighboring hooks people confuse it with. TypeScript-first.

The Hand-Rolled Guard

There's no mystery about how to skip a mount run — every React codebase past a certain age contains this:

function SearchFilters({ filters }: { filters: Filters }) {
  const isFirst = useRef(true);

  useEffect(() => {
    if (isFirst.current) {
      isFirst.current = false;
      return;
    }
    trackEvent("filters_changed", filters); // not on page load, please
  }, [filters]);
  // ...
}

It works. The problem isn't correctness, it's that the guard is per effect: the ref, the check, and the flip get re-typed into every effect that needs the behavior, and the actual intent — three words, "skip the mount" — is buried under six lines of ceremony. Variants of the recipe also rot in review: someone "simplifies" the flag into useState and buys an extra render, or copies the guard into a second effect but shares one ref between them, so whichever effect runs first consumes the skip and the other one fires on mount anyway.

The fix is the standard one for boilerplate with a name: give it the name.

useUpdateEffect — useEffect, Minus the Mount

import { useState } from 'react';
import { useUpdateEffect } from '@reactuses/core';

function EditorSettings({ userId }: { userId: string }) {
  const [settings, setSettings] = useState(loadDefaults);

  useUpdateEffect(() => {
    saveSettings(userId, settings);
    toast("Settings saved ✓");
  }, [settings]);

  return <SettingsForm value={settings} onChange={setSettings} />;
}

On mount: nothing — no phantom save, no toast over a form the user hasn't touched. On every settings change after that: exactly what useEffect would do. The signature is useEffect's, verbatim:

function useUpdateEffect(effect: React.EffectCallback, deps?: React.DependencyList): void;

Dependency array, cleanup function returned from the effect, all of it behaves the way your useEffect instincts say it should. There is nothing new to learn, which is the point.

Four Lines, One Primitive

The implementation is a wrapper so thin it's almost embarrassing to walk through — almost:

const createUpdateEffect = (hook) => (effect, deps) => {
  const isFirstMount = useFirstMountState();

  hook(() => {
    if (!isFirstMount) {
      return effect();
    }
  }, deps);
};

export const useUpdateEffect = createUpdateEffect(useEffect);

And the primitive underneath, useFirstMountState, which answers "is this the first render?" by flipping a ref during render:

export const useFirstMountState = (): boolean => {
  const isFirst = useRef(true);
  if (isFirst.current) {
    isFirst.current = false;
    return true;
  }
  return isFirst.current;
};

Two details are worth pausing on. First, the effect itself still runs on mount — React registers it, diffs the deps, schedules the callback as usual. What's skipped is your function inside it. That matters because it means the deps array is live from render one; the second render's diff has something real to compare against. Second, createUpdateEffect is a factory over the effect hook, which is how useUpdateLayoutEffect exists: same skip, useLayoutEffect timing, for when the update-only work measures or mutates the DOM before paint.

Cleanup follows from "your callback never ran": there's nothing to clean up after mount, so the first cleanup runs before the second update-run of your effect — and on unmount, if your effect has run at least once, its cleanup fires normally. The library's own test suite pins that down.

The StrictMode Gotcha — Verified, Not Rumored

Here's the section most useUpdateEffect write-ups skip, and it's the one that will actually bite you. Wrap the component in <StrictMode> on React 18+ and run it in development:

const effect = jest.fn();

function Comp() {
  const [c, setC] = useState(0);
  useUpdateEffect(() => { effect(c); }, [c]);
  // ...
}

render(<StrictMode><Comp /></StrictMode>);
// effect.mock.calls.length === 2   ← on MOUNT. Twice.

That's not a hypothetical — it's the output of a test against the real implementation. The "skip the first run" hook runs on mount, twice, in StrictMode dev. Here's the chain:

StrictMode double-invokes the render function. The first invocation flips the ref: useFirstMountState returns true. The second invocation — same component instance, same ref — finds it already flipped and returns false. Instrumenting the hook shows exactly [true, false] across the two passes.
The committed render is the second one, so the effect closure captures isFirstMount === false. The guard is already defeated before any effect runs.
StrictMode then runs effects twice (mount → simulated unmount → remount), and both runs sail through the open guard. Two calls.

Before you file the bug: this isn't a reactuse defect, it's the collision StrictMode exists to cause. Flipping a ref during render is how essentially every ref-based first-mount detector works, and "how many times has this function rendered" is precisely the kind of hidden render-count dependency StrictMode's double-invocation is designed to smoke out. Production builds don't double-invoke, so in production the skip works exactly as advertised — the divergence is dev-only.

The practical guidance:

Use useUpdateEffect for UX-grade skips — toasts, autosaves, analytics, refetch-on-filter-change. A dev-only extra firing costs you nothing real, and in production it behaves.
Don't use it for correctness-grade guarantees — "this network call must never happen at mount" enforced only by useUpdateEffect will happen at mount on every StrictMode dev run, and you'll burn an afternoon on it. Correctness wants a condition on data, not on render count: compare against the previous value with usePrevious, or check the actual state ("form is dirty") before firing.

If you've ever seen a "my useUpdateEffect runs on mount!" issue on a hooks library — this is what happened, every time.

Don't Confuse It With Its Neighbors

The effect family has some near-collision names, and picking wrong is a category error rather than a bug, so — a field guide:

useMount is the mirror image: runs the callback only on mount, never on updates. Between it and useUpdateEffect, the two halves of useEffect get names.
useUpdate — despite the name — is not in this family at all. It returns a function that forces a re-render. If you reached for it wanting "effect on update," you wanted this post's hook instead.
useUpdateLayoutEffect is the same skip on useLayoutEffect timing — update-only DOM measurement without a flash of unpainted state.
useDeepCompareEffect solves the other classic effect complaint: deps compared by Object.is, so a fresh object literal re-fires every render. If your effect over-fires because of object identity rather than mount timing, that's the hook you want.
useFirstMountState is the primitive itself — reach for it directly when you need first-render awareness during render (e.g., skipping an animation class on initial paint), not inside an effect.

Real Use Cases

Autosave that respects hydration. Form state arrives from the server or localStorage; saving it back on mount is at best a wasted write and at worst clobbers fresher data with defaults. Save on change. (Debounce it too — useDebounceFn composes cleanly inside the callback.)
Change notifications. "Theme updated", "Filters applied", "Copied!" — feedback for an action. On mount there was no action, so a toast on page load reads as a glitch. This is the single most common reason people go looking for this hook.
Skip the duplicate initial fetch. The page was server-rendered with data, or the first payload came down in props; the effect exists to *re*fetch when the query changes. Mount run = an immediate second request for data already on screen.
Analytics on transitions. trackEvent("sort_changed", sort) should mean the user changed the sort — not that the component mounted with a default. Pair with usePrevious when the event payload needs from → to.

SSR Safety

Nothing to guard. Effects never run during server rendering — that's React, not the library — and useFirstMountState touches no window, no document, only a ref. Server render, hydration, first client render: your callback stays unfired through all three, then wakes on the first real update. SSR-safe by construction, like every hook in @reactuses/core aims to be — though this one earns it by simply having nothing to get wrong.

Takeaways

useEffect runs on mount; sometimes you meant "on change only." useUpdateEffect is that intent with a name — same signature, same cleanup, minus one invocation.
The implementation is a four-line wrapper over useFirstMountState; the effect still registers on mount, only your callback is skipped, so deps tracking starts from render one.
StrictMode dev fires it on mount — twice — and that's verified, not folklore. Double-invoked renders defeat any ref-flipped-during-render guard. Production is unaffected. Use it for UX-grade skips; enforce correctness-grade rules on data, not render counts.
Mind the name collisions: useMount is the complement, useUpdate is a re-render trigger from a different universe, and identity-caused over-firing wants useDeepCompareEffect.
SSR-safe with zero ceremony — effects don't run on the server, and the mount skip carries through hydration untouched.

Grab it from @reactuses/core and let your effects stop celebrating their own birth.

React usePrevious Hook: Track Previous State & Props (2026)

ReactUse — Wed, 29 Jul 2026 01:35:27 +0000

React usePrevious Hook: Track Previous State & Props (2026)

React gives you the current value of state and props on every render — and no built-in way to ask what the value was before. So everyone copies the same ten-line recipe: stash the value in a ref inside useEffect, return ref.current. It works in the demo, ships to production, and then one day a "count went up ↑" indicator starts claiming nothing changed — because the component re-rendered for a completely unrelated reason and the ref quietly overwrote its own history.

usePrevious from @reactuses/core tracks the previous distinct value instead of the previous render's value, using the pattern the React docs themselves recommend — no refs, no effects, no drift. The whole implementation is twelve lines, so this post walks through the real bug in the classic recipe, why the fix looks illegal but isn't, and the one gotcha that can send it into an infinite loop. TypeScript-first.

The Classic Recipe, and Where It Frays

This is the version that lives in a thousand blog posts and probably a few of your codebases:

function usePrevious<T>(value: T): T | undefined {
  const ref = useRef<T>();
  useEffect(() => {
    ref.current = value;
  });
  return ref.current;
}

Render, then the effect fires and copies the current value into the ref. Next render reads the ref — the value from one render ago. The subtle part is in that last phrase: this hook returns the value from the previous render, not the previous value. Those are the same thing only as long as the only reason your component re-renders is the value changing. It never stays that way.

Watch it break. A counter with a direction indicator, plus one unrelated piece of state:

function Counter() {
  const [count, setCount] = useState(0);
  const [dark, setDark] = useState(false);
  const prevCount = usePrevious(count); // the ref version

  return (
    <div>
      <button onClick={() => setCount(count + 1)}>+1</button>
      <button onClick={() => setDark(!dark)}>toggle theme</button>
      {prevCount !== undefined && prevCount !== count && (
        <span>{count > prevCount ? "↑ went up" : "↓ went down"}</span>
      )}
    </div>
  );
}

Click +1: count is 5, prevCount is 4, the indicator shows "↑ went up". Correct. Now click toggle theme: count hasn't moved, but the component re-renders, the effect runs again, and the ref becomes 5. On the next render prevCount === count, and the indicator vanishes — the component now believes the count never changed. Any parent re-render, context update, or sibling state change does the same thing. The comparison you built the hook for is exactly what the hook corrupts.

This isn't a hypothetical: it's the same failure reported against react-use, ahooks, and reactuse itself before the implementation was replaced.

usePrevious — Previous Value, Not Previous Render

import { useState } from 'react';
import { usePrevious } from '@reactuses/core';

function Counter() {
  const [count, setCount] = useState(0);
  const [dark, setDark] = useState(false);
  const prevCount = usePrevious(count);

  return (
    <div>
      <button onClick={() => setCount(count + 1)}>+1</button>
      <button onClick={() => setDark(!dark)}>toggle theme</button>
      <p>Now: {count}, before: {prevCount ?? "—"}</p>
    </div>
  );
}

The signature:

function usePrevious<T>(value: T): T | undefined;

Toggle the theme as many times as you like — prevCount stays 4, because the count never actually changed. On the first render it returns undefined, since there is no prior value yet; type your comparisons as T | undefined accordingly.

The implementation is short enough to quote in full, and it contains no refs and no effects:

export function usePrevious<T>(value: T): T | undefined {
  const [current, setCurrent] = useState<T>(value);
  const [previous, setPrevious] = useState<T>();

  if (value !== current) {
    setPrevious(current);
    setCurrent(value);
  }

  return previous;
}

Wait — setState During Render?

Yes, and it's not a hack: it's the pattern from the React docs, under storing information from previous renders. Calling a setter while rendering is legal under two conditions, and this code meets both:

It's the component's own state. React handles a render-phase update by throwing away the current render's output and immediately re-running the component with the new state — before touching the DOM, before painting, before any effect runs. No intermediate frame is ever visible.
It's behind a condition that eventually goes quiet. value !== current is true for exactly one render after a change; the re-run then sees value === current and falls through. No loop.

Compare what each version anchors its history to. The ref recipe records "whatever the value was last render" — so every render rewrites history, related or not. The state version records "whatever the value was before it last changed" — unrelated re-renders hit value === current and touch nothing. That single guard is the entire bug fix.

It also holds up under React 18's stricter execution models, where the effect-and-ref version gets shakier. StrictMode double-invokes render functions in development: here, the second invocation runs the same comparison against the same state and lands in the same place — idempotent. Concurrent features can throw a render away before committing: a discarded render's state updates are discarded with it, whereas a ref mutation inside a render (the other popular "fix") escapes the render and leaks into a timeline that officially never happened. State-during-render is the one variant that's correct under all of it.

The Gotcha: Unstable Objects

The comparison is !== — strict reference equality. Feed the hook a fresh object literal every render and value !== current is always true:

// 💥 Too many re-renders
const prev = usePrevious({ x: position.x, y: position.y });

Every render creates a new object, the guard fires, the render-phase setState triggers a re-run, which creates another new object, and React halts the whole thing with "Too many re-renders." The fix is the usual referential-stability discipline: pass primitives, or memoize the object so its identity only changes when its contents do:

const point = useMemo(() => ({ x, y }), [x, y]);
const prevPoint = usePrevious(point); // ✅

Primitives — numbers, strings, booleans — are always safe, and they're what you're tracking ninety percent of the time. (If your real problem is "run an effect when a deeply-nested object actually changes," that's useDeepCompareEffect's job, not this hook's.)

usePrevious vs useLatest

The two get confused because both are "a hook holding a value across time," but they answer opposite questions:

usePrevious answers "what was this value before it changed?" — for comparisons during render: direction of change, from/to labels, transition detection.
useLatest answers "what is this value right now?" from inside a stale closure — a setInterval callback, a debounced handler, an event listener registered once on mount.

If you're rendering a diff, you want usePrevious. If a callback keeps seeing an old value, you want useLatest. Needing one is never a sign you need the other.

Real Use Cases

Direction of change. Sort arrows, price tickers, scroll direction, "↑ 3 more than yesterday" — anything rendered from value > prev. This is the case the ref recipe visibly breaks, since one unrelated re-render erases the direction.
Transition detection. Fire logic when a prop crosses a boundary, not merely when it's in a state: prevStatus === "loading" && status === "success" shows a toast exactly once per completed request. Pair with useUpdateEffect to also skip the mount render.
From → to animations. Number tickers and chart transitions need both endpoints; usePrevious hands you the starting value for the tween without a second piece of state.
"Changed from X to Y" UI. Audit-style forms and settings panels that show what edits are pending — render prev and value side by side; on the first render prev is undefined and you show nothing.

SSR Safety

usePrevious is two useState calls and a comparison — no window, no document, no effects, nothing to guard. On the server it renders once and returns undefined, the client's first render returns the same undefined, and hydration matches by construction. Unlike hooks that read browser state (a cookie, localStorage, a media query), there is no server/client divergence to design around. It's SSR-safe the boring way: by not doing anything.

Takeaways

The classic useRef + useEffect recipe tracks the previous render, not the previous *value* — any unrelated re-render silently rewrites it, which is precisely the bug filed against every major hooks library that shipped it.
usePrevious uses setState-during-render — the React-docs-sanctioned pattern: conditional, self-terminating, invisible to the user, and correct under StrictMode and concurrent rendering.
First render returns undefined — there's no history yet; type against T | undefined.
Comparison is by reference — pass primitives or useMemo-stabilized objects, or the render-phase guard fires forever and React stops you with "Too many re-renders."
Previous value vs current value in a closure are different problems — comparisons want usePrevious; stale callbacks want useLatest.

Grab it from @reactuses/core and let "previous" actually mean previous.

DEV Community: ReactUse

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

Quick Start

Why Not autoFocus, activeElement, or Plain CSS?

The Manual Way — and Where It Bites

The useFocus API

Real Patterns

Floating labels — the label knows when to float

Validate on blur, not on keystroke

Press / to search

Autofocus that survives conditional rendering

useFocus vs Its Siblings

Production Notes

Takeaways

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

Quick Start

Why Not window.innerWidth or a Media Query?

The Manual Way — and Where It Bites

The useElementSize API

Which box should you measure?

The crisp-canvas trick

Real Patterns

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

Responsive charts that re-layout at rest

How many columns fit?

useElementSize vs Its Siblings

Production Notes

Takeaways

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

Quick Start

What SSE Actually Is (60 Seconds)

The Manual Way — and Where It Bites

The useEventSource API

Named events, declaratively

Auto-reconnect with a budget

Connect lazily

The Wall Every SSE Tutorial Hits: Auth Headers

Streaming an AI response, token by token

Native or fetch-based — which one?

Production Notes

When SSE Is the Wrong Tool

Takeaways

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

Quick Start

What useMount Actually Is

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

useUnmount — and the Stale-Closure Trap It Avoids

Async Work on Mount

The Mirror Image: Skipping the Mount

When Not to Use useMount

Takeaways

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

The Problem in Thirty Seconds

The Full API

How It Works Inside

useEvent vs useCallback

useEvent vs React's useEffectEvent

Patterns

A Handler Prop That Doesn't Break React.memo

Subscriptions That Never Re-Subscribe

Timers — or Just Use the Library's

Stable Callbacks for Imperative Widgets

The Rules

Takeaways

Barrel Files: Why index.ts Re-Exports Hurt Tree Shaking, Next.js Dev Memory, and tsc (2026)

What Is a Barrel File?

Harm #1: Tree Shaking Becomes Fragile (or Silently Impossible)

Harm #2: Next.js Dev and tsc Pay the Full Graph, in Time and Memory

optimizePackageImports — and the catch we hit

Harm #3: Barrels Breed Circular Dependencies

What To Do Instead

In application code

As a library author

Takeaways

React useMeasure Hook: Measure DOM Elements with ResizeObserver (2026)

The Simplest Case: A Live-Sized Container

The Full API

The contentRect Gotcha: top/left Are Not Viewport Coordinates

How It Works Inside

useMeasure vs useElementSize vs useElementBounding vs useResizeObserver

Press `/` to search

`optimizePackageImports` — and the catch we hit

`distance` — Fire Before the Edge

`direction` — Not Just Bottom

`preserveScrollPosition` — Stay Where You Were