DEV Community: reactuse.com

React useResizeObserver Hook: Track Element Size Changes (2026)

reactuse.com — Tue, 21 Jul 2026 09:53:10 +0000

React useResizeObserver Hook: Track Element Size Changes (2026)

A chart component reads its container's width once on mount and draws itself to fit. Then the user collapses the sidebar. The container just gained 300 pixels, the window never resized, no resize event fired — and the chart is now sitting in a too-wide box, drawn for a layout that no longer exists. Listening to window.resize misses every way an element can change size without the window changing: a sidebar toggling, a flex sibling appearing, content loading in above, an accordion expanding.

The browser's answer is ResizeObserver — a native API that watches an element, not the window. useResizeObserver from @reactuses/core wraps it with the lifecycle handled: observe on mount, disconnect on unmount, no stale observers left behind. Everything below is the real API, TypeScript-first.

The Manual Version, and Where It Frays

Wiring ResizeObserver into a component by hand looks simple enough:

function Chart() {
  const ref = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (!ref.current) return;
    const observer = new ResizeObserver((entries) => {
      redraw(entries[0].contentRect.width);
    });
    observer.observe(ref.current);
    return () => observer.disconnect();
  }, []);

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

This works — until it meets real component code. The common ways it frays:

The callback needs props or state. The empty dependency array means the observer keeps calling the callback from the first render. Add the dependencies and the observer is torn down and re-created on every change instead. Neither is what you want.
The options object re-triggers the effect. Put { box: 'border-box' } inline in the dependency array and it's a new object every render — the observer disconnects and reconnects continuously.
The target isn't a ref. Sometimes the element comes from a callback, a portal, or document.querySelector. The effect-plus-ref pattern needs rewiring for each shape.

None of these are hard individually. But this is lifecycle plumbing you'd be re-deriving in every component that cares about its own size — and each copy is one refactor away from a leak or an observe/disconnect loop.

useResizeObserver — The Native API, Lifecycle Handled

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

function Chart() {
  const ref = useRef<HTMLDivElement>(null);

  useResizeObserver(ref, (entries) => {
    redraw(entries[0].contentRect.width);
  });

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

The signature:

function useResizeObserver(
  target: BasicTarget<Element>,
  callback: ResizeObserverCallback,
  options?: ResizeObserverOptions
): () => void;

Three things worth noting, because they're where the hand-rolled version frays:

The target is flexible. BasicTarget accepts a ref object, a plain Element, or a getter function returning one — so the same hook covers the ref case, the querySelector case, and the "element isn't mounted yet" case (null/undefined targets are simply not observed until they exist).
The callback is the native ResizeObserverCallback. You get the real ResizeObserverEntry[] — contentRect, borderBoxSize, contentBoxSize — not a simplified wrapper. And changing the callback between renders doesn't tear down and re-attach the observer; the hook keeps one observer per target instead of cycling it on every render.
Options are deep-compared. Passing { box: 'border-box' } inline is fine — the hook compares by value, not identity, so a fresh object literal each render doesn't churn the observer.

The return value is a stop() function: call it to disconnect early — say, once a measurement has been taken and you no longer care. Otherwise cleanup happens automatically on unmount.

The `box` Option

ResizeObserverOptions has one field, box, and it decides what "size" means:

`box` value	What's measured
`'content-box'` (default)	Content only — excludes padding and border
`'border-box'`	Content + padding + border — what the element occupies in layout
`'device-pixel-content-box'`	Content box in physical device pixels — for pixel-perfect canvas work

For most layout logic, the default is right. Reach for 'border-box' when you're matching the element's footprint in the layout, and 'device-pixel-content-box' when sizing a <canvas> backing store so it stays crisp on high-DPI screens.

Just Want the Numbers? useElementSize and useMeasure

useResizeObserver hands you raw observer entries, which is what you want for imperative work — redrawing a chart, syncing a canvas. But often the goal is simply reactive size as state. Two hooks in @reactuses/core are built directly on top of useResizeObserver for exactly that:

useElementSize — width and height as a tuple:

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

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

  return (
    <div ref={ref}>
      {width}px × {height}px
    </div>
  );
}

It respects the same box option (and correctly sums fragmented boxes via borderBoxSize/contentBoxSize), starting at [0, 0] until the first measurement lands.

useMeasure — the full content rect, when you need more than width and height:

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

function Panel() {
  const ref = useRef<HTMLDivElement>(null);
  const [rect, stop] = useMeasure(ref);
  // rect: { x, y, width, height, top, left, bottom, right }

  return <div ref={ref}>{rect.width}px wide</div>;
}

If you've used the standalone react-use-measure package, this is the same idea — one dependency fewer if you're already on @reactuses/core.

Picking the Right Size Hook

The element category has several hooks that sound alike; they answer different questions:

Hook	Answers	Updates on
`useResizeObserver`	"Run this code when the element resizes"	Element resize (raw entries)
`useElementSize`	"How big is this element?"	Element resize
`useMeasure`	"What's this element's content rect?"	Element resize
`useElementBounding`	"Where is this element in the viewport?"	Element resize and window scroll/resize
`useWindowSize`	"How big is the window?"	Window resize

The one distinction that trips people up: useMeasure reports the observer's content rect (size-driven), while useElementBounding reports getBoundingClientRect() — viewport-relative position — and also refreshes on scroll. Positioning a tooltip or overlay? useElementBounding. Responding to size? useElementSize or useMeasure. The broader observer family — intersection, mutation, resize — is compared in React Observer Hooks.

Real Use Cases

Container-driven responsive components. A component that switches layout based on its own width — not the viewport's — works correctly in a sidebar, a modal, or a split pane. This is the container-query mindset, available as plain state.
Charts and canvas. Redraw exactly when the drawing surface changes, including sidebar toggles and flex reflows that window.resize never sees. Pair with 'device-pixel-content-box' for crisp high-DPI canvases.
Virtualized lists. Row measurement for variable-height virtualization: observe each row, feed real heights back to the virtualizer.
Auto-growing textareas and clamped text. Detect when content overflows its box and toggle "show more" affordances based on measured, not assumed, size.
Element-size media queries. Swap a toolbar from icons+labels to icons-only the moment its container gets tight, regardless of what the window is doing.

SSR-Safe by Construction

ResizeObserver doesn't exist on the server. All three hooks only touch it inside effects, and target resolution is guarded — during server rendering nothing runs, useElementSize returns [0, 0], useMeasure returns a zeroed rect, and hydration proceeds without a ReferenceError. No typeof window checks in your code. If you're auditing hand-rolled browser-API code for the same gap, SSR-Safe React Hooks covers the pattern.

Takeaways

window.resize misses most element resizes — sidebar toggles, flex reflows, content changes. ResizeObserver watches the element itself, and useResizeObserver handles its lifecycle: observe on mount, disconnect on unmount, plus a stop() for early exit.
The target is flexible — ref, element, or getter — and null targets are handled, so mount-order gymnastics disappear.
Callback and options don't churn the observer. Inline callbacks and inline options objects are fine; the hook keeps one observer per target.
box decides what "size" means — content-box by default, border-box for layout footprint, device-pixel-content-box for canvas work.
Want state instead of entries? useElementSize for [width, height], useMeasure for the full rect, useElementBounding when viewport position matters too.
SSR-safe — no observer construction on the server, no guards in your code.

Grab it from @reactuses/core and let your components respond to the size they actually have.

React useObjectUrl Hook: Preview Files & Blobs Without Memory Leaks (2026)

reactuse.com — Fri, 10 Jul 2026 03:11:51 +0000

React useObjectUrl Hook: Preview Files & Blobs Without Memory Leaks (2026)

A user uploads a dozen images to a gallery editor. Each one gets a live preview via URL.createObjectURL(). The session runs for twenty minutes, previews get swapped as files are added and removed, and the tab's memory usage climbs the entire time — because every createObjectURL() call has to be paired with a revokeObjectURL() call, and that pairing has to survive re-renders, prop changes, and unmounts. Most components get it wrong, and the bug is invisible until someone leaves the tab open long enough to notice the fan spin up.

useObjectUrl is the one-line fix: hand it a File, Blob, or MediaSource, get back a URL string, and never call revokeObjectURL yourself again. Everything below is the real @reactuses/core API, TypeScript-first.

The Manual Version, and Where It Leaks

URL.createObjectURL() is the browser API behind every client-side file preview: pass it a Blob (a File is one) and it hands back a blob: URL you can drop straight into an <img src> or <video src>. The catch is on the other end — every URL it mints stays alive, holding a reference to the underlying data, until you explicitly call URL.revokeObjectURL(). Forget that call, or call it at the wrong time, and the URL — and the memory behind it — never gets released.

In a React component, "the wrong time" is easy to hit:

function FilePreview({ file }: { file?: File }) {
  const [url, setUrl] = useState<string>();

  useEffect(() => {
    if (!file) return;
    const next = URL.createObjectURL(file);
    setUrl(next);
    return () => URL.revokeObjectURL(next);
  }, [file]);

  return url ? <img src={url} /> : null;
}

This one is actually correct — the cleanup closes over next, not over state, so it always revokes exactly the URL it created. But it's correct in the way hand-rolled effects tend to be: one careless refactor away from breaking. Move the URL.createObjectURL call outside the effect, memoize it wrong, or read url from state instead of the local next, and the pairing silently comes apart. Multiply this pattern across every component that previews a file — an avatar uploader, a chat attachment, a gallery thumbnail — and you're maintaining the same fragile lifecycle logic in five different places.

useObjectUrl — Create and Revoke, Handled

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

function FilePreview({ file }: { file?: File }) {
  const url = useObjectUrl(file);
  return url ? <img src={url} /> : null;
}

That's the whole hook. The signature:

function useObjectUrl(object: Blob | MediaSource): string | undefined;

Pass a Blob (or the File subtype of it) or a MediaSource, get back the object URL — or undefined before a source exists. Internally it's one useEffect: call URL.createObjectURL() when the source is present, and return a cleanup that calls URL.revokeObjectURL(). The difference from the hand-rolled version isn't behavior, it's that the pairing lives in one audited place instead of being re-derived per component.

When the Source Changes — and When It Unmounts

The revoke fires in both cases that matter:

The source changes. Swap the file prop for a different File and the hook revokes the old URL before minting the new one — no accumulation as a user clicks through a list of attachments.
The component unmounts. Close the preview modal, navigate away, remove the item from a list — the cleanup runs and the URL is released. Nothing is left waiting for a garbage collector that doesn't know to collect it.

That second case is the one hand-rolled code most often skips, because it only shows up as a slow memory creep during actual use, not in a quick manual test.

Real Use Cases

File input previews. Show the image, video, or PDF a user just selected before they commit to uploading it — the canonical case.
Blob API responses. An endpoint that returns a Blob (a generated export, a signed asset, a fetch().blob() result) can be turned into a downloadable <a href> or an inline <img>/<video> without writing it to disk.
Canvas exports. canvas.toBlob() produces a Blob; feed it straight into useObjectUrl to preview or offer a download of what the user just drew or cropped.
MediaSource for custom video players. MediaSource is the Media Source Extensions object behind adaptive streaming and custom-buffered video — you build the stream programmatically, then still need a URL to hand to <video src>. useObjectUrl accepts it directly, same as a Blob.

SSR-Safe by Construction

URL.createObjectURL doesn't exist on the server — there's no DOM, no Blob URLs to mint. useObjectUrl never touches the URL API during server rendering; it returns undefined until the effect runs on the client, so there's no typeof window guard to remember and no server crash to debug. If you're auditing other hand-rolled browser-API code for the same gap, SSR-Safe React Hooks covers the general pattern.

The File-Handling Trio

useObjectUrl is one piece of a small set of hooks that cover the full file lifecycle — picking a file, dropping a file, and previewing it:

Hook	Role
`useFileDialog`	Opens the native file picker, returns the selected `FileList`
`useDropZone`	Turns any element into a drag-and-drop target for files
`useObjectUrl`	Turns the resulting `File`/`Blob` into a safe, auto-revoked preview URL

Wire a useFileDialog or useDropZone result straight into useObjectUrl and the preview step needs no cleanup code at all. The full walkthrough — including a multi-file gallery that combines all three — is in React File Handling.

Takeaways

The core problem is a pairing bug. Every URL.createObjectURL() needs a matching URL.revokeObjectURL(), and re-deriving that pairing correctly in every component that shows a file preview is where memory leaks creep in.
useObjectUrl(object) takes a Blob (or File) or MediaSource and returns the URL string, or undefined before a source exists.
Revocation is automatic on both triggers that matter: the source changing and the component unmounting.
Covers more than image previews: Blob API responses, canvas.toBlob() exports, and MediaSource for custom video players.
SSR-safe — returns undefined on the server, no URL API access, no guard code needed.
Pairs with useFileDialog and useDropZone to cover selection, drop, and preview with zero manual lifecycle management.

Grab it from @reactuses/core and stop auditing components for missing revokeObjectURL calls.

React useLocalStorage Hook: SSR-Safe Persistent State (2026)

reactuse.com — Thu, 09 Jul 2026 02:04:39 +0000

React useLocalStorage Hook: SSR-Safe Persistent State (2026)

The user spends two minutes setting up filters on your dashboard, hits refresh, and everything resets. useState is ephemeral by design — every reload starts from scratch. The fix everyone knows is localStorage; the wiring everyone writes for it — a useState initializer that reads storage plus a useEffect that writes it back — ships at least four bugs: it crashes or mismatches under SSR, it throws on corrupted data, it desyncs across browser tabs, and two components using the same key silently drift apart.

useLocalStorage is the hook that gets all of it right. It looks exactly like useState, but the value survives reloads, serializes more than just strings, stays in sync across tabs and across components, and renders safely on the server. Everything below is the real @reactuses/core API, TypeScript-first.

Why Not Just useState + useEffect?

Here is the version that ends up in most codebases, and it's buggier than it looks:

function usePersistedState(key: string, defaultValue: string) {
  const [value, setValue] = useState(() => {
    const stored = localStorage.getItem(key); // 🐛 see below
    return stored !== null ? JSON.parse(stored) : defaultValue;
  });

  useEffect(() => {
    localStorage.setItem(key, JSON.stringify(value));
  }, [key, value]);

  return [value, setValue] as const;
}

It breaks under SSR. On the server there is no localStorage, so the initializer throws. Guard it with typeof window and you trade the crash for a hydration mismatch: the server rendered the default, the client immediately renders the stored value, and React warns — or worse, silently patches the wrong DOM.
It throws on bad data. JSON.parse over a value that was hand-edited, half-written, or saved by an older version of your app takes the whole component down with it.
It ignores other tabs. The user changes the setting in tab A; tab B keeps showing — and re-saving — the stale value until a full reload.
It ignores other components. Two components calling usePersistedState('theme', …) each hold their own useState. One updates, the other doesn't re-render. Same key, two truths.

Each bug is fixable by hand, and the fixes add up to exactly what a good hook already is.

useLocalStorage — useState That Survives Reloads

The API is deliberately shaped like useState: a tuple of value and setter, with the default as the second argument.

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

function Settings() {
  const [layout, setLayout] = useLocalStorage('dashboard-layout', 'grid');

  return (
    <select value={layout ?? 'grid'} onChange={(e) => setLayout(e.target.value)}>
      <option value="grid">Grid</option>
      <option value="list">List</option>
    </select>
  );
}

The signature is useLocalStorage(key, defaultValue, options?):

const [value, setValue] = useLocalStorage<T>(key, defaultValue, options);
// value: T | null      setValue: Dispatch<SetStateAction<T | null>>

On first visit value is the default; after any setValue, the value is written to localStorage and comes back on the next reload. Functional updates work exactly like useState's: setValue(prev => …) receives the current stored value. The only visible difference from useState is the type: value is T | null, because a persisted key can also be removed — more on that below.

Objects, Maps, Sets, Dates — Serialization Is Automatic

localStorage only stores strings; the hook picks the right serializer for you by looking at the type of the default value. Pass an object and it round-trips through JSON.stringify/JSON.parse; pass a number and you get a number back, not "42":

const [filters, setFilters] = useLocalStorage('filters', {
  status: 'open',
  assignee: null as string | null,
});

const [fontSize, setFontSize] = useLocalStorage('font-size', 16);
const [seen, setSeen] = useLocalStorage('seen-ids', new Set<string>());
const [lastVisit, setLastVisit] = useLocalStorage('last-visit', new Date());

That last pair is the part hand-rolled versions never handle: Map, Set, and Date defaults get dedicated serializers (Set → JSON array, Date → ISO string, and back), so seen is a real Set with .has() after a reload — not a stringified husk.

When the built-ins don't fit — say the value needs to stay compatible with a format some other system wrote — pass your own:

const [config, setConfig] = useLocalStorage('legacy-config', defaultConfig, {
  serializer: {
    read: (raw) => parseLegacyFormat(raw),
    write: (value) => toLegacyFormat(value),
  },
});

Removing the Key: setValue(null)

Persisted state has one operation useState doesn't: forget this. Setting the value to null removes the key from localStorage entirely:

const [token, setToken] = useLocalStorage<string>('auth-token', null);

// login
setToken(response.token);
// logout — key is deleted from localStorage, value becomes null
setToken(null);

This is why the value's type is T | null. A removed key stays null for the rest of the session — it does not snap back to the default — which is what you want: "logged out" and "never logged in with a default" are different states, and the hook doesn't blur them.

SSR and Hydration, Actually Safe

useLocalStorage is built on useSyncExternalStore — React's own primitive for subscribing to external data — with a server snapshot that returns the default value. That one design choice buys three things:

No crash on the server. The hook never touches window or localStorage during server rendering. No typeof window guard in your code.
No hydration mismatch. The client's first render deliberately matches the server HTML (the default), then React re-renders with the stored value through the proper useSyncExternalStore path — no warning, no patched-over DOM.
Concurrent-safe reads. Because storage is treated as an external store, React 18+ features like transitions never see a torn value.

The one thing no localStorage hook can eliminate is the brief flash of the default before the stored value appears — the server genuinely doesn't know what's in the browser's storage. For values where that flash hurts (theme is the classic), the fix lives outside React, in a blocking inline script; the trade-offs are covered in SSR-Safe React Hooks.

And when storage itself is unavailable — some privacy modes, or storage access that throws — the hook degrades to a plain in-memory state holder and reports the failure through onError instead of crashing:

const [draft, setDraft] = useLocalStorage('draft', '', {
  onError: (e) => trackWarning('storage unavailable', e), // default: console.error
});

The same onError catches corrupted data (the JSON.parse bug from the naive version — the hook returns the default instead of throwing) and quota-exceeded writes.

In Sync Across Tabs — and Across Components

Change the value in one tab and every other tab updates instantly, because the hook listens to the browser's native storage event:

// Tab A and Tab B both render this — flip it in one, both update.
const [theme, setTheme] = useLocalStorage('theme', 'light');

Cross-tab sync is on by default; opt out with listenToStorageChanges: false if a tab should keep its own view until reload.

The subtler half is same-tab sync. The native storage event never fires in the tab that made the change, so in a hand-rolled hook, a theme toggle in the header updates the header — and the sidebar reading the same key keeps its stale copy. useLocalStorage re-broadcasts every write internally, so every component on the same key re-renders together, always. Two components, one key, one truth — the drift bug from the naive version simply doesn't exist. (If you're syncing more than persisted state across tabs, Cross-Tab State in React covers the full toolbox.)

The Storage Family

useLocalStorage has siblings; pick by where the value should live and how long:

Hook	Persists in…	Survives	Cross-tab
`useLocalStorage`	`localStorage`	reloads + browser restarts	✅ synced
`useSessionStorage`	`sessionStorage`	reloads, per tab	❌ per-tab by design
`useCookie`	cookies	per cookie options; sent to the server	✅
`useBroadcastChannel`	nothing (messaging only)	—	✅ live messaging

useSessionStorage shares the exact same API and serialization — swap the import and the value becomes per-tab. useCookie is the one to reach for when the server needs the value on the first request (which is also the real fix for the theme-flash problem). useBroadcastChannel isn't storage at all, but it's the right tool when tabs need to talk rather than persist.

Takeaways

The hand-rolled useState + useEffect + localStorage combo ships four bugs: SSR crash or hydration mismatch, JSON.parse crashes on bad data, no cross-tab sync, and drift between components sharing a key.
useLocalStorage(key, defaultValue) is a drop-in useState that persists — same tuple, same functional updates, typed T | null.
Serialization is automatic and driven by the default's type — objects, arrays, numbers, booleans, and even Map, Set, and Date round-trip correctly. Custom serializer when you need a specific format.
setValue(null) removes the key — "cleared" is a real state, distinct from the default.
Built on useSyncExternalStore: SSR-safe with no guards, hydration-mismatch-free, and it degrades to in-memory state (with onError) when storage is blocked.
Sync is total: native storage events across tabs (toggle with listenToStorageChanges), internal re-broadcast across components in the same tab — always on.
Same API, different lifetime: useSessionStorage for per-tab, useCookie when the server needs it too.

Grab it from @reactuses/core and let refresh stop meaning reset.

React useReducedMotion Hook: Respect prefers-reduced-motion (2026)

reactuse.com — Wed, 08 Jul 2026 04:05:32 +0000

React useReducedMotion Hook: Respect prefers-reduced-motion (2026)

A full-bleed parallax hero. An auto-scrolling carousel. A loading spinner that spins, bounces, and rotates. For most users that's just "modern." For someone with a vestibular disorder, migraine with aura, or Meniere's disease, it can trigger real nausea, dizziness, or a headache bad enough to close the tab — not annoyance, an actual physical symptom. That's why every major OS ships a "Reduce Motion" toggle (iOS since 2013, macOS, Windows, Android, GNOME), and why CSS exposes it to the web as the prefers-reduced-motion media feature.

useReducedMotion is the hook that reads that setting into React state — reactively, so it updates the instant the user flips the OS toggle, and safely, so it doesn't touch window during SSR. This post covers the real @reactuses/core API, what prefers-reduced-motion actually asks you to remove (it's narrower than "no motion at all"), and the three integration patterns you'll actually reach for.

The Naive Version

The obvious approach is window.matchMedia inside an effect:

function Hero() {
  const [reduce, setReduce] = useState(false);

  useEffect(() => {
    const mql = window.matchMedia('(prefers-reduced-motion: reduce)');
    setReduce(mql.matches);
    // 🐛 forget this and the value never updates again
    const onChange = () => setReduce(mql.matches);
    mql.addEventListener('change', onChange);
    return () => mql.removeEventListener('change', onChange);
  }, []);

  return <div className={reduce ? 'hero' : 'hero hero--parallax'} />;
}

Three ways this goes wrong in practice. First, window doesn't exist on the server, so this whole block needs a guard the moment you're on Next.js, Remix, or Astro — and it's easy to reach for typeof window !== 'undefined' sprinkled through render instead of isolating it in an effect. Second, people initialize the state once with mql.matches and skip the change listener entirely — which works fine until a user actually toggles the setting while your tab is open (switching a laptop from battery to plugged-in triggers this on some OSes, and QA almost never tests it). Third, every component that cares about motion preference reimplements this same matchMedia + listener + cleanup dance.

The API

useReducedMotion is one call:

const prefersReducedMotion = useReducedMotion(defaultState?: boolean): boolean;

defaultState — optional, defaults to false. This is the value returned during SSR and on the very first client render, before the media query can be evaluated.
returns — a boolean that starts as defaultState and updates live whenever the user's OS-level motion preference changes. No manual listener, no cleanup to forget.

Under the hood it's genuinely this simple — the whole implementation is a one-line call into useMediaQuery:

export function useReducedMotion(defaultState?: boolean) {
  return useMediaQuery('(prefers-reduced-motion: reduce)', defaultState);
}

useMediaQuery is the hook doing the actual work — constructing the MediaQueryList inside an effect (so nothing touches matchMedia during render or on the server) and subscribing to its change event for you. useReducedMotion just pins the query string. That's the whole value: you get the right query, spelled correctly, wired up correctly, every time.

Pattern 1: Kill a Single Animation

The smallest use — gate one CSS transition or class on the flag:

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

function Hero() {
  const reduce = useReducedMotion();

  return (
    <div className={reduce ? 'hero' : 'hero hero--parallax'}>
      <h1>Welcome</h1>
    </div>
  );
}

.hero--parallax carries the transform: translateY(...) scroll-linked animation; the base .hero class doesn't. No JS animation logic runs at all when reduce is true — you're not just skipping the visual motion, you're skipping the scroll-listener or requestAnimationFrame loop driving it, which is also a real performance win on lower-end devices.

Pattern 2: Framer Motion / GSAP Integration

If you're using an animation library, the hook value plugs straight into its duration/transition config instead of a class swap:

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

function Card({ children }: { children: React.ReactNode }) {
  const reduce = useReducedMotion();

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

Note this doesn't remove the fade — opacity isn't the kind of motion prefers-reduced-motion is about (see the next section). It removes the displacement: with reduce true, y never moves and the transition is instant, so the card just appears. Framer Motion also ships its own useReducedMotion hook that does the same matchMedia read — if you're already pulling in @reactuses/core for everything else, this hook keeps you on one source of truth instead of two libraries independently reading the same media query.

Pattern 3: One Global Switch Instead of N Guards

Gating every individual animation with reduce ? ... : ... scales badly once a design system has dozens of animated components. The pattern that scales is: read the hook once, near the app root, and drive a data- attribute that a global stylesheet reacts to.

function App({ children }: { children: React.ReactNode }) {
  const reduce = useReducedMotion();

  return (
    <div data-motion={reduce ? 'reduce' : 'no-preference'}>
      {children}
    </div>
  );
}

[data-motion="reduce"] *,
[data-motion="reduce"] *::before,
[data-motion="reduce"] *::after {
  animation-duration: 0.01ms !important;
  animation-iteration-count: 1 !important;
  transition-duration: 0.01ms !important;
  scroll-behavior: auto !important;
}

This is the same shape as the classic CSS-only universal-selector rule built directly on the media query — the difference is the data-motion attribute is driven by React state, so the exact same flag is available to your JS animation logic (Pattern 2) and your CSS (this pattern) without reading the media query twice or risking the two getting out of sync.

What "Reduce" Doesn't Mean

prefers-reduced-motion: reduce is not "disable all motion." WCAG 2.3.3 and the platform vendors are specifically after large-scale, non-essential motion: parallax scrolling, autoplaying background video, zooming/panning hero animations, auto-advancing carousels, bouncing/spinning decorative loaders. Motion that carries information or confirms an interaction — a checkbox's tick animation, a button's brief press state, a spinner indicating "still loading," drag-and-drop feedback — is generally fine to keep, ideally just shorter and calmer. Removing every pixel of movement, including a :hover color transition, isn't what the setting is asking for and can make an interface feel broken rather than accessible. When in doubt, ask "does this motion span a large portion of the screen, or run continuously without user action?" — that's the motion to gate.

One more nuance worth knowing: if you only need this in CSS and never in JS logic, Tailwind's motion-reduce: variant (or a plain @media (prefers-reduced-motion: reduce) block) gets there with zero JavaScript. Reach for the hook specifically when the decision needs to reach into render or effect logic — choosing between an autoplaying <video> and a static poster image, skipping a scroll-driven animation library's setup entirely, or the data-attribute pattern above.

SSR Safety

useReducedMotion is safe to render on the server. useMediaQuery only calls window.matchMedia inside an effect — which React never runs during SSR — so the server and the very first client paint both use defaultState (false unless you pass otherwise). There's no typeof window guard to write and no hydration mismatch: React reconciles the same value on both passes, and the real preference is read and applied on the client right after mount. (For the general pattern behind this, see SSR-Safe React Hooks.)

The Preference-Query Family

useReducedMotion is one of a small set of hooks that read OS-level accessibility and display preferences — all thin, purpose-named wrappers over the same primitive:

Hook	Media query	Returns
`useReducedMotion`	`prefers-reduced-motion`	`boolean`
`usePreferredColorScheme`	`prefers-color-scheme`	`"dark" \
{% raw %}`usePreferredContrast`	`prefers-contrast`	`"more" \
{% raw %}`usePreferredDark`	`prefers-color-scheme: dark`	`boolean`
`useMediaQuery`	any query you pass	`boolean`

Reach for the named ones first — they exist so the query string is spelled correctly once, in one place — and drop down to useMediaQuery directly for anything more specific, like a custom breakpoint. For the wider set of hooks that make a React app respect what the user already configured at the OS level, see React and User Preferences; for the broader accessibility toolkit, see Building Accessible React Components with Hooks.

Takeaways

prefers-reduced-motion isn't a nice-to-have — for users with vestibular disorders or migraine triggers, ignoring it can make a page physically unusable.
useReducedMotion(defaultState?) reads it reactively: a one-line wrapper over useMediaQuery('(prefers-reduced-motion: reduce)', defaultState), so it inherits SSR-safety and live updates for free.
Gate individual transitions for one-off cases (Pattern 1), feed it into Framer Motion/GSAP transition configs (Pattern 2), or drive a global data-motion attribute once at the app root so CSS and JS share one source of truth (Pattern 3).
The setting targets large-scale or non-essential motion — parallax, autoplay, decorative loops — not every :hover transition. Keep short, functional motion; cut the rest.
SSR-safe by default: defaultState covers the server and first paint, no typeof window guard needed.

Grab it from @reactuses/core — it's one hook standing between your animations and a user who can't safely look at them.

React useIntersectionObserver Hook: Lazy Load & Detect Visibility (2026)

reactuse.com — Tue, 30 Jun 2026 09:21:01 +0000

React useIntersectionObserver Hook: Lazy Load & Detect Visibility (2026)

You want to load an image only when it scrolls near the viewport. Or fire an analytics event the first time a card is actually seen. Or trigger "load more" when the user reaches the bottom of a list. Every one of these is the same question — is this element on screen yet? — and for years the answer was a scroll listener that fired hundreds of times a second, re-read getBoundingClientRect() on each tick, and still managed to miss the edge cases.

IntersectionObserver is the browser API that answers that question correctly, asynchronously, and off the main thread. useIntersectionObserver is the hook that wires it into React without the useEffect/useRef/cleanup boilerplate — and without the leak-on-unmount and stale-closure bugs the hand-rolled version always ships. This post covers the real @reactuses/core API, the three patterns you'll actually reach for, and how to tune threshold, rootMargin, and root. SSR-safe and typed.

Why Not Just Use a Scroll Listener?

The old way to know whether an element was visible looked like this: listen to scroll, and on every event measure the element against the viewport.

useEffect(() => {
  function onScroll() {
    const rect = el.getBoundingClientRect();
    if (rect.top < window.innerHeight) {
      setVisible(true);
    }
  }
  window.addEventListener('scroll', onScroll);
  return () => window.removeEventListener('scroll', onScroll);
}, []);

This has two problems baked in. First, scroll fires on the main thread, dozens of times per second, and getBoundingClientRect() forces a synchronous layout each time — that's exactly the recipe for janky scrolling. Second, it only catches elements crossing the viewport; the moment your scroll happens inside a container, you're re-deriving geometry by hand.

IntersectionObserver flips the model. You hand the browser a target and a threshold, and it tells you — asynchronously, batched, off the scroll path — when the element crosses that threshold. No measuring, no listener thrash. The only thing left to get wrong is the React lifecycle around it, and that's the part the hook owns.

Here's the naive in-component version, which has the same three bugs every hand-rolled observer does:

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

  useEffect(() => {
    const el = ref.current;
    if (!el) return;
    const io = new IntersectionObserver(([entry]) => {
      if (entry.isIntersecting) setSeen(true); // 🐛 see below
    }, { threshold: 0.1 });
    io.observe(el);
    return () => io.disconnect();
  }, []);

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

It leaks if you forget the cleanup. Drop the return () => io.disconnect() — and people do, especially when refactoring — and the observer outlives the component.
It captures stale closures. The moment the callback references a prop or a second piece of state, the observer created on mount freezes whatever those were at mount time, not when it fires.
It spreads. Every lazy section, every "viewed" tracker, every infinite-scroll sentinel re-implements the same useRef + observe + disconnect dance, and each copy is a fresh chance to ship one of the first two bugs.

A hook fixes all three in one place.

The API

useIntersectionObserver takes three arguments and returns a stop function:

const stop = useIntersectionObserver(target, callback, options?);

target — what to observe. A React ref, a raw element, or a getter () => element. (It accepts null/undefined too, so observing a conditionally-rendered element is safe — the hook simply waits.)
callback — the standard IntersectionObserverCallback, (entries, observer) => void. You get the raw IntersectionObserverEntry[], so you decide what visibility means for your case.
options — the native IntersectionObserverInit: { root, rootMargin, threshold }. All optional.
returns stop() — call it to disconnect the observer early (more on this below). The hook also calls it for you automatically on unmount.

The deliberate design choice here is that the hook is callback-based, not boolean-based. It doesn't decide for you that "intersecting" means visible — because depending on the job, it might mean "10% visible", "fully visible", or "within 200px of the viewport". You read entry.isIntersecting (or entry.intersectionRatio) and act. If all you want is a plain boolean, there's a convenience sibling for that — see below.

Internally the callback is kept in a ref (via useLatest), so it never goes stale — bug #2 is gone even when your callback closes over props. And because the observer is only ever constructed inside an effect, the hook is SSR-safe: nothing touches IntersectionObserver during render.

Pattern 1: Lazy-Load an Image

The canonical use. Render a placeholder, and only swap in the real <img> once the container is about to enter the viewport. Note the stop() call — once we've loaded, we never need the observer again, so we disconnect it immediately.

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

function LazyImage({ src, alt }: { src: string; alt: string }) {
  const ref = useRef<HTMLDivElement>(null);
  const [loaded, setLoaded] = useState(false);

  const stop = useIntersectionObserver(
    ref,
    ([entry]) => {
      if (entry.isIntersecting) {
        setLoaded(true);
        stop(); // one-shot: stop observing once we've committed to loading
      }
    },
    { rootMargin: '200px' }, // start loading 200px before it scrolls in
  );

  return (
    <div ref={ref} style={{ minHeight: 200 }}>
      {loaded ? <img src={src} alt={alt} /> : <div className="skeleton" />}
    </div>
  );
}

Two things make this feel right. The rootMargin: '200px' grows the observer's "viewport" by 200px on every side, so the fetch kicks off before the image is actually visible and the user rarely sees the skeleton. And stop() inside the callback means a list of 500 lazy images ends up with zero live observers once they've all loaded — no lingering work as you keep scrolling.

Pattern 2: Fire-Once "Viewed" Analytics

Tracking which sections a user actually scrolled to is the same shape — but here you genuinely want it to fire exactly once, so the stop() is doing real work.

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

function TrackedSection({ id, children }: { id: string; children: React.ReactNode }) {
  const ref = useRef<HTMLElement>(null);

  const stop = useIntersectionObserver(
    ref,
    ([entry]) => {
      if (entry.isIntersecting) {
        analytics.track('section_viewed', { id });
        stop(); // count each section once, not once per scroll-past
      }
    },
    { threshold: 0.5 }, // "viewed" = at least half on screen
  );

  return <section ref={ref}>{children}</section>;
}

Here threshold: 0.5 encodes a product decision — a section only counts as "viewed" once 50% of it is on screen, so a fast scroll past the top edge doesn't inflate your numbers. The stop() guarantees one event per section per page load even if the user scrolls it in and out repeatedly.

Pattern 3: Infinite-Scroll Trigger

Put an empty sentinel <div> at the bottom of a list and fetch the next page when it intersects. Note that here we don't call stop() — we want the trigger to keep firing for every page.

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

function Feed({ items, loadMore, hasMore }: FeedProps) {
  const sentinel = useRef<HTMLDivElement>(null);

  useIntersectionObserver(sentinel, ([entry]) => {
    if (entry.isIntersecting && hasMore) {
      loadMore();
    }
  });

  return (
    <>
      {items.map((it) => <Row key={it.id} item={it} />)}
      {hasMore && <div ref={sentinel} style={{ height: 1 }} />}
    </>
  );
}

Because the callback is always the latest one (no stale closure), loadMore and hasMore are read fresh every time the sentinel intersects — the bug that bites the hand-rolled useEffect version doesn't exist here. If you want this whole pattern packaged, useInfiniteScroll builds exactly this on top, including the scroll-container plumbing.

Tuning: threshold, rootMargin, and root

The third argument is the native IntersectionObserverInit, passed straight through. Three knobs, each answering a different question:

useIntersectionObserver(ref, callback, {
  threshold: 0.5,        // HOW MUCH must be visible to count?
  rootMargin: '200px',   // grow/shrink the trigger boundary
  root: containerRef.current, // WHAT are we measuring against?
});

threshold — a number (or array) from 0 to 1 for how much of the target must be visible before the callback fires. 0 (the default) fires the instant a single pixel crosses; 1 waits until the element is fully on screen. Pass an array like [0, 0.25, 0.5, 0.75, 1] to get a callback at each step — useful for scroll-linked animations driven by entry.intersectionRatio.
rootMargin — a CSS-margin string that inflates or deflates the root's bounding box before intersection is computed. Positive values ('200px') fire early — the lazy-load-ahead trick from Pattern 1. Negative values ('-100px 0px') fire late, e.g. "only count this as viewed once it's 100px past the top edge."
root — the element you're measuring against. Defaults to the browser viewport; set it to a scroll container's element when your list scrolls inside a <div> rather than the page.

The stop() Return Value

The returned stop() disconnects the observer. You usually don't need it — the hook auto-disconnects on unmount — but it's the clean way to express one-shot observation, as in Patterns 1 and 2: the first time the element intersects, do the work and stop watching. That's both a correctness win (the event fires exactly once) and a performance one (no live observer trailing behind a long, already-loaded list).

Just Want a Boolean?

Sometimes you don't care about entries or thresholds — you just want a reactive isVisible flag for the whole viewport. useElementVisibility wraps useIntersectionObserver and hands you exactly that, as a tuple with its own stop:

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

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

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

Reach for useElementVisibility when a boolean is all you need, and drop down to useIntersectionObserver the moment you want a custom root, a non-default threshold, multiple thresholds, or the raw entry. Same engine, two ergonomics.

SSR Safety

useIntersectionObserver is safe to render on the server. It constructs the IntersectionObserver only inside an effect — which React never runs on the server — and the underlying element lookup returns undefined outside the browser, so there's no typeof window guard to write and no hydration mismatch to chase. Drop it into a Next.js, Remix, or Astro component as-is. (If SSR-safety is a recurring theme in your codebase, SSR-Safe React Hooks goes deeper.)

The Visibility & Size Family

useIntersectionObserver is the low-level primitive in a family of DOM-watching hooks. Pick by what you actually want back:

Hook	Gives you	Reach for it when…
`useIntersectionObserver`	raw entries, a `stop()`	you want full control: custom root, thresholds, one-shot
`useElementVisibility`	`[isVisible, stop]`	a plain "is it on screen?" boolean is enough
`useInfiniteScroll`	a load-more callback wired up	you're building a paginated/infinite list
`useResizeObserver`	a callback on size change	the element's size matters, not its visibility
`useElementSize`	`{ width, height }` as state	you just need live width/height
`useElementBounding`	the full bounding rect	you need viewport-relative position (changes on scroll)

For the full tour of how these compose, see React Observer Hooks: 7 Ways to Watch the DOM.

Takeaways

A scroll listener plus getBoundingClientRect() is the wrong tool for "is this on screen" — it thrashes the main thread and still misses scroll containers. IntersectionObserver answers it correctly, batched and off the scroll path.
useIntersectionObserver(target, callback, options?) wires it into React: hand it a ref, a callback that receives the raw entries, and the native options. It returns a stop() and auto-disconnects on unmount.
It's callback-based on purpose — you decide what "visible" means via entry.isIntersecting / entry.intersectionRatio. The callback is never stale, so it reads fresh props every time it fires.
Call stop() inside the callback for one-shot jobs (lazy-load, fire-once analytics); skip it for repeating triggers (infinite scroll).
Tune with threshold (how much must show), rootMargin (fire early/late), and root (measure against a container, not the viewport).
Want just a boolean? useElementVisibility returns [isVisible, stop]. Both are SSR-safe.

Grab it from @reactuses/core and delete your scroll-listener boilerplate.

React useDebounce Hook: Debounce State & Callbacks (2026)

reactuse.com — Mon, 29 Jun 2026 02:26:06 +0000

You have a search box. The user types react hooks, and your component fires an API request on every single keystroke — eleven requests for one query, ten of them already stale by the time they resolve. The fix everyone reaches for is debouncing: wait until the typing stops, then fire once. The fix everyone gets wrong is writing that debounce by hand with setTimeout inside a component, where stale closures, missing cleanup, and re-render churn quietly break it.

useDebounce is the hook that gets it right. This post covers the two shapes you actually need — debouncing a value and debouncing a callback — when to use each, and how to cancel or flush pending calls. Everything here is the real @reactuses/core API, SSR-safe and typed.

Why Not Just Use setTimeout?

Debouncing itself is simple: delay a function until a quiet period has passed, restarting the timer on every new call. (If you want the full conceptual breakdown — and how it differs from throttling — see Debounce vs Throttle in React.) The hard part is doing it inside a React component. Here is the naive version, and it has three bugs:

function Search() {
  const [query, setQuery] = useState('');
  const timer = useRef<ReturnType<typeof setTimeout>>();

  function handleChange(e: React.ChangeEvent<HTMLInputElement>) {
    const value = e.target.value;
    setQuery(value);
    clearTimeout(timer.current);
    timer.current = setTimeout(() => {
      fetchResults(value); // 🐛 see below
    }, 300);
  }

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

It leaks on unmount. If the component unmounts while a timer is pending, the callback still fires 300 ms later — often setting state on a gone component, or hitting an API for a screen the user already left.
It captures stale values. The moment you debounce anything other than the raw event value — a second piece of state, a prop, a derived value — the closure freezes whatever those were when the timer was set, not when it fires.
It spreads. Every place that needs debouncing re-implements the useRef + clearTimeout dance, and each copy is a chance to forget the cleanup.

A hook fixes all three in one place. ReactUse ships two, built on the battle-tested lodash.debounce internally so the edge cases (leading edge, max wait, trailing edge) are already handled.

useDebounce — Debounce a Value

The most common case: you have a value that changes rapidly and you want a second, lagging copy of it that only updates after things settle. That second copy is what you feed into expensive work.

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

function Search() {
  const [query, setQuery] = useState('');
  const debouncedQuery = useDebounce(query, 300);

  useEffect(() => {
    if (!debouncedQuery) return;
    fetchResults(debouncedQuery);
  }, [debouncedQuery]);

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

The signature is useDebounce(value, wait?, options?) and it returns the debounced value, with the same type as the input:

const debounced = useDebounce(value, 300);

The input (query) updates on every keystroke, so the controlled <input> stays perfectly responsive — that's the value you bind to the DOM. The output (debouncedQuery) only catches up 300 ms after the user stops typing, so it's the value you put in the effect's dependency array. The API fires once per pause instead of once per keystroke, and your input never feels laggy because the thing you typed into was never the thing being debounced.

This pattern — fast value for the UI, debounced value for the side effect — is the whole point. Keep them as two separate variables and the rest falls into place.

useDebounceFn — Debounce a Callback

Debouncing a value is great when the thing you want to throttle is state. But sometimes you want to debounce an action that takes arguments — an autosave, an analytics event, a resize handler — without routing it through state first. That's useDebounceFn:

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

function Editor({ docId }: { docId: string }) {
  const { run } = useDebounceFn((content: string) => {
    saveDraft(docId, content);
  }, 1000);

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

useDebounceFn(fn, wait?, options?) returns an object with three members:

const { run, cancel, flush } = useDebounceFn(fn, 1000);

run — the debounced function. Call it as often as you like; fn only actually executes after the calls stop for wait ms. It forwards every argument through, so run(content) calls fn(content).
cancel — drop any pending invocation. Nothing fires.
flush — fire the pending invocation right now, instead of waiting out the timer.

Crucially, run always calls the latest version of your fn. Internally the hook keeps your callback in a ref, so even though the debounced wrapper is created once, it never goes stale — the docId closure problem from the setTimeout version simply doesn't exist here. And the hook cancels any pending call automatically on unmount, so bug #1 is gone too.

useDebounce is actually built on top of useDebounceFn — it debounces a setState call and hands you the resulting value. Same engine, two ergonomics.

cancel and flush in practice

The cancel/flush pair is what raw setTimeout makes painful and a hook makes trivial. Two real cases:

function CommentBox() {
  const { run: autosave, cancel, flush } = useDebounceFn(
    (text: string) => saveDraft(text),
    2000,
  );

  return (
    <>
      <textarea onChange={(e) => autosave(e.target.value)} />
      {/* User hit "Post" — persist immediately, don't wait out the 2s */}
      <button onClick={() => flush()}>Post</button>
      {/* User hit "Discard" — throw away the pending autosave */}
      <button onClick={() => cancel()}>Discard</button>
    </>
  );
}

flush guarantees the in-flight draft is written before the post request goes out; cancel makes sure a discarded draft doesn't get saved a beat later. Both are one call.

Value or Callback — Which One?

A quick decision rule:

Reach for useDebounce when you're debouncing a piece of state that something else reads — a search term, a filter, a slider value feeding a chart. You want a lagging value.
Reach for useDebounceFn when you're debouncing an action with arguments — autosave, logging, firing a network request directly. You want a lagging function, plus cancel/flush control.

If you find yourself creating a piece of state only to debounce it and then immediately fire an effect, useDebounceFn is usually the more direct tool.

Tuning: leading, trailing, and maxWait

The optional third argument is passed straight through to lodash.debounce, so you get its full options object:

useDebounce(value, 300, {
  leading: false,  // don't fire on the very first call (default)
  trailing: true,  // fire after the pause (default)
  maxWait: 1000,   // …but never wait longer than 1s total
});

Two knobs worth knowing:

leading: true fires on the first call immediately, then debounces the rest. Good for "respond instantly, then settle" interactions — the first click of a button feels snappy while rapid repeats are absorbed.
maxWait caps the total delay. With a pure trailing debounce, a user who types continuously for ten seconds gets zero updates until they stop. maxWait: 1000 forces an update at least once a second even mid-burst — the difference between a search box that feels alive and one that feels frozen.

SSR Safety

Both hooks are safe to render on the server. They touch no window, document, or browser timer during render — the debounced work only ever runs inside effects, which React never executes on the server. Drop them into a Next.js, Remix, or Astro component and there's no typeof window guard to write, no hydration warning to chase. (If SSR-safety is a running theme in your codebase, SSR-Safe React Hooks goes deeper.)

The Rate-Limiting Family

useDebounce has three close relatives in ReactUse; pick by what you're limiting and which shape you need:

Hook	Limits a…	Strategy
`useDebounce`	value	debounce (fire after the pause)
`useDebounceFn`	callback	debounce, with `cancel`/`flush`
`useThrottle`	value	throttle (fire at a fixed rate)
`useThrottleFn`	callback	throttle, with `cancel`/`flush`

The throttle pair mirrors the debounce pair exactly — same (value/fn, wait, options) signature, same return shapes — but enforces a steady cadence instead of waiting for silence. Use throttle for things that should update during a continuous gesture (scroll position, drag coordinates, a live progress readout); use debounce for things that should update only after it ends (search, autosave, validation). The full mental model is in Debounce vs Throttle in React: When to Use Which.

Takeaways

A hand-rolled setTimeout debounce inside a component ships three bugs by default: it leaks on unmount, it captures stale closures, and it gets copy-pasted.
useDebounce(value, wait) gives you a lagging copy of a value — type into the fast one, run effects off the slow one. Perfect for search-as-you-type.
useDebounceFn(fn, wait) debounces an action and hands you { run, cancel, flush }. run always calls your latest callback (no stale closures) and auto-cancels on unmount.
Use flush to commit a pending call early (submit) and cancel to drop it (discard).
The third argument is lodash.debounce options — leading for instant-first-call, maxWait to cap the delay so long bursts still update.
Both are SSR-safe and sit alongside useThrottle/useThrottleFn for the fixed-rate case.

Grab them from @reactuses/core and delete your clearTimeout boilerplate.

React useIsomorphicLayoutEffect: Fix the SSR useLayoutEffect Warning (2026)

reactuse.com — Thu, 25 Jun 2026 03:22:51 +0000

You added a useLayoutEffect to measure a tooltip, shipped it, and the next time your Next.js (or Remix, or Gatsby) dev server rendered a page on the server, the console lit up:

Warning: useLayoutEffect does nothing on the server, because its effect cannot
be encoded into the server renderer's output format. This will lead to a
mismatch between the initial, non-hydrated UI and the intended UI. To avoid
this, useLayoutEffect should only be used in components that render exclusively
on the client.

The warning is correct, the suggested fix ("only use it on the client") is unhelpful, and the obvious workaround — just switch to useEffect — quietly reintroduces the visual bug you used useLayoutEffect to kill in the first place. useIsomorphicLayoutEffect is the small hook that resolves the standoff. This post explains exactly why the warning happens, why the two naive fixes are both wrong, and what the one-line hook actually does.

Why useLayoutEffect Exists At All

React gives you two effect hooks that look nearly identical:

useEffect runs after the browser has painted. Its callback is queued and fires asynchronously once the frame is on screen.
useLayoutEffect runs before the browser paints, synchronously, right after React has mutated the DOM but before the user sees anything.

That timing difference is the whole point. If you need to read layout — getBoundingClientRect, scrollHeight, the measured width of a node — and then write a style based on it, you have to do it before paint. Otherwise the user sees one frame of the wrong layout, then a flicker as your useEffect corrects it. The canonical example is a tooltip that has to position itself relative to its own measured size:

function Tooltip({ targetRect, children }) {
  const ref = useRef<HTMLDivElement>(null);
  const [pos, setPos] = useState({ top: 0, left: 0 });

  useLayoutEffect(() => {
    const { height, width } = ref.current!.getBoundingClientRect();
    // place the tooltip above the target, centered
    setPos({
      top: targetRect.top - height - 8,
      left: targetRect.left + targetRect.width / 2 - width / 2,
    });
  }, [targetRect]);

  return <div ref={ref} style={{ position: 'fixed', ...pos }}>{children}</div>;
}

With useLayoutEffect, React measures and repositions in the same synchronous pass, so the tooltip is only ever painted in the right spot. Swap in useEffect and the tooltip flashes at { top: 0, left: 0 } for one frame before jumping into place. On a fast machine you might not notice; on a throttled phone you absolutely will.

Why the Server Hates It

Server-side rendering produces an HTML string. There is no browser, no DOM, no layout phase, and — critically — nothing ever paints. The entire reason useLayoutEffect exists is to run synchronously before a paint that, on the server, never comes.

So React makes a deliberate choice: useLayoutEffect callbacks do not run during server rendering at all. They can't be meaningfully serialized into the HTML, and running them would do nothing useful. React knows this is a footgun — your component's server output won't reflect whatever the layout effect would have computed — so it emits that warning to tell you the server HTML and the intended client UI may not match.

The warning is not a bug in your code. It is React pointing out that you have a hook whose only job is impossible to do on the server.

Why You Can't Just Use useEffect

The first instinct is to silence the warning by switching to useEffect, which React is perfectly happy to run on the server (it just defers the callback). The warning disappears. The flicker comes back.

Remember the timing: useEffect fires after paint. So on the client, after hydration, your measure-then-reposition logic now runs one frame late. The user sees the un-positioned state first, then the correction. You traded a console warning for a visible visual glitch — a strictly worse outcome, because at least the warning was invisible to users.

The second instinct — render the component only on the client (typeof window !== 'undefined' guards, dynamic imports with ssr: false, mounting flags) — works but throws away server rendering for that whole subtree. You lose the SSR HTML, the content is invisible to crawlers until hydration, and you've added a layout-shift on first load. That's a sledgehammer for a hook-selection problem.

The Actual Fix: Branch on Environment

The realization is simple: you want useLayoutEffect's pre-paint timing in the browser, and you want useEffect's "quietly do nothing useful, no warning" behavior on the server. Those are two different hooks, and which one is correct depends entirely on where the code is running.

So pick at module-load time based on whether you're in a browser:

import { useEffect, useLayoutEffect } from 'react';

const isBrowser = typeof window !== 'undefined';

export const useIsomorphicLayoutEffect = isBrowser ? useLayoutEffect : useEffect;

That is the entire hook. In the browser it is useLayoutEffect — identical pre-paint, synchronous timing, identical signature. On the server it is useEffect, which React never warns about and which never runs a useless layout pass. "Isomorphic" is the old term for code that runs the same way on server and client; the hook picks the right same-meaning effect for each environment.

ReactUse ships exactly this as useIsomorphicLayoutEffect, so you don't copy-paste the snippet into every project:

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

function Tooltip({ targetRect, children }) {
  const ref = useRef<HTMLDivElement>(null);
  const [pos, setPos] = useState({ top: 0, left: 0 });

  // Same code as before — but no SSR warning, and no client flicker.
  useIsomorphicLayoutEffect(() => {
    const { height, width } = ref.current!.getBoundingClientRect();
    setPos({
      top: targetRect.top - height - 8,
      left: targetRect.left + targetRect.width / 2 - width / 2,
    });
  }, [targetRect]);

  return <div ref={ref} style={{ position: 'fixed', ...pos }}>{children}</div>;
}

It's a drop-in replacement for useLayoutEffect: same callback, same optional dependency array, same cleanup function. The only thing that changes is that the warning goes away and your client behavior stays identical.

One subtlety: why the branch lives outside render

Notice the isBrowser ? useLayoutEffect : useEffect runs once, at module evaluation, not inside the component. That's deliberate. The Rules of Hooks require that you call the same hooks in the same order on every render. If you wrote if (isBrowser) useLayoutEffect(...) else useEffect(...) inside the component, you'd technically be calling different hooks on server vs client — and worse, the linter would (rightly) complain about a conditional hook call.

By resolving the choice to a single stable function reference at module load, the component just calls useIsomorphicLayoutEffect(...) unconditionally. isBrowser never changes within a process, so the selected hook is constant for the lifetime of the bundle. Hook order stays stable; the lint rule stays happy.

When To Reach For It (And When Not)

Use useIsomorphicLayoutEffect when all of these are true:

You need layout-phase timing — you're measuring or mutating the DOM and the result must be on screen in the first painted frame (tooltips, popovers, autosizing textareas, scroll restoration, focus management, anything where a one-frame flash is visible).
The component is server-rendered (Next.js, Remix, Astro islands, Gatsby, TanStack Start — anything that calls renderToString/renderToPipeableStream).
You want the SSR warning gone without disabling SSR for the subtree.

Do not reach for it as a blanket replacement for useEffect. If your effect doesn't touch layout — fetching data, subscribing to an event, syncing to localStorage, logging — plain useEffect is correct and you want its post-paint, non-blocking timing. useLayoutEffect (and therefore the isomorphic version) runs synchronously and blocks paint; overusing it makes your app feel janky for no benefit. The rule of thumb hasn't changed: reach for layout effects only when you'd otherwise see a flicker.

And if a component is genuinely client-only — it imports window at the top level, or wraps a browser-only library — rendering it client-side (dynamic(() => ..., { ssr: false })) is still the right tool. useIsomorphicLayoutEffect is for components that do render on the server and just have a layout effect inside them.

The Layout-Timing Family

useIsomorphicLayoutEffect is the base of a small family of effect hooks in ReactUse. Once you understand the SSR-safe layout-effect, the rest fall out naturally:

useUpdateLayoutEffect — a layout effect that skips the first mount and only runs on updates. Internally it wraps useLayoutEffect with a first-mount guard, so it's the layout-phase sibling of useUpdateEffect. Handy when the initial DOM is already correct and you only need to react to subsequent prop changes (animating a value to a new position, not into existence). Note that this one uses useLayoutEffect directly — combine the pattern with an isBrowser branch if you need it SSR-silent.
useUpdateEffect — the same skip-first-render behavior on top of useEffect. The everyday "run this on change but not on mount" hook.
useMount — runs a callback exactly once after mount. A readable alias for useEffect(fn, []) when all you mean is "on mount".

There's also a quietly important consumer of this hook inside the library itself. useEvent — ReactUse's stable-callback hook, the one that gives you an event handler with a permanent identity but always-fresh closure — uses useIsomorphicLayoutEffect to sync the latest function into a ref before paint:

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

Writing the ref in the layout phase guarantees that if any child fires the handler during its layout effect, it already sees the newest version — and doing it isomorphically means useEvent itself never trips the SSR warning. It's a good illustration of why a library hook reaches for the isomorphic variant by default: you don't know which environment your consumers run in, so you pick the one that's correct in both.

Takeaways

The warning "useLayoutEffect does nothing on the server" is React telling you a pre-paint hook can't run where there's no paint. It's accurate, not a false alarm.
Switching to useEffect silences the warning but reintroduces a one-frame flicker on the client, because useEffect runs after paint.
useIsomorphicLayoutEffect resolves both: it is useLayoutEffect in the browser and useEffect on the server, chosen once at module load so hook order stays stable.
Use it for layout measurement/mutation in server-rendered components; keep plain useEffect for everything that doesn't touch layout.
ReactUse ships it (and the related useUpdateLayoutEffect, useUpdateEffect, useMount) so you don't reinvent the one-liner — and uses it internally to keep its own hooks SSR-safe.

Browse the full set of SSR-safe effect hooks at reactuse.com, and drop useIsomorphicLayoutEffect in wherever a useLayoutEffect is making your server console nervous.

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

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

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

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

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

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

The Bug, in One Component

A draggable card that follows the mouse:

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

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

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

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

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

1. useRafFn — The Loop, With Pause and Resume

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

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

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

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

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

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

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

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

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

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

2. useRafState — useState That Coalesces Per Frame

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

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

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

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

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

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

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

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

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

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

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

3. useFps — Measuring What You Built

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

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

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

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

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

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

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

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

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

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

4. useDevicePixelRatio — Drawing at the Right Resolution

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Putting It Together: A 60fps Spring-Following Cursor

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

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

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

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

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

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

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

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

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

When to Reach for Which

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

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

Installation

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

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

Related Hooks

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

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

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

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

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

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

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

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

The Bug, in One useEffect

A search box that fetches results when the user types:

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

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

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

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

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

1. useEventListener — addEventListener, Without the Leak

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

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

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

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

A ref-targeted variant looks the same:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

3. useKeyModifier — Modifier State That Stays in Sync

The naive way to track whether Shift is currently held:

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

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

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

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

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

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

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

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

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

4. useTextSelection — Observe Selection Without the Loop

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

useTextSelection handles both halves of that:

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

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

  if (!text) return null;

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

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

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

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

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

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

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

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

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

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

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

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

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

6. useThrottleFn — At Most Once Per N Milliseconds

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

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

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

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

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

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

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

Putting It Together: A Keyboard-Aware Selection Toolbar

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

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

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

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

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

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

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

  React.useEffect(updateRect, [selection]);

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

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

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

When to Reach for Which

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

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

Installation

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

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

Related Hooks

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

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

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

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

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

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

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

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

Why Pointer Events Are a Swamp

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

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

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

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

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

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

1. useHover — Hover State That Does Not Flicker

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

5. useClickOutside — Dismiss on Outside Click, Through Portals

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

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

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

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

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

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

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

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

6. useScratch — Relative Pointer Position During a Drag

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

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

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

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

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

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

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

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

Putting It Together: A Context Menu

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

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

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

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

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

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

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

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

When to Reach for Which

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

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

Installation

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

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

Related Hooks

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

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

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

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

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

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

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

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

The Bug, Concretely

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

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

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

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

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

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

1. useLatest — Always Read the Current Value

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

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

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

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

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

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

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

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

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

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

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

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

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

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

3. useMountedState — Don't setState After Unmount

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

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

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

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

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

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

4. usePrevious — Compare Against the Last Render

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

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

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

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

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

5. useFirstMountState — Know If This Is the First Render

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

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

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

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

  return null;
}

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

6. useUpdate — Force a Re-render on Demand

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

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

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

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

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

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

7. useMergedRefs — Point Many Refs at One Node

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

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

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

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

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

Putting It Together

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

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

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

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

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

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

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

Try Them Out

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

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

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

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

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

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

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

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

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

Why useEffect Alone Is Not Enough

Take a single line from a real component:

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

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

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

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

1. useAsyncEffect — async/await Without the IIFE

The pattern everyone writes the first time:

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

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

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

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

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

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

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

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

2. useUpdateEffect — Skip the Mount

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

The workaround in plain React is a ref:

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

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

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

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

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

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

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

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

useMount is a one-purpose alias that documents intent:

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

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

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

4. useUnmount — Cleanup Without the Empty Effect

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

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

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

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

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

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

5. useDeepCompareEffect — When Your Deps Are Objects

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

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

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

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

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

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

6. useCustomCompareEffect — Deep Compare, Your Rules

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

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

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

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

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

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

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

7. useOnceEffect — Run Exactly Once, With Reactive Deps

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

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

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

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

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

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

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

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

8. useIsomorphicLayoutEffect — Stop the SSR Warnings

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

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

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

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

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

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

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

9. useUpdateLayoutEffect — The Layout Variant of useUpdateEffect

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

useUpdateLayoutEffect shines for layout-driven animations:

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

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

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

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

When to Use Which: A Decision Table

The full set, in one place:

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

Three rules to keep in mind:

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

A Realistic Combination

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

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

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

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

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

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

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

Try Them Out

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

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

DEV Community: reactuse.com

React useResizeObserver Hook: Track Element Size Changes (2026)

React useResizeObserver Hook: Track Element Size Changes (2026)

The Manual Version, and Where It Frays

useResizeObserver — The Native API, Lifecycle Handled

The box Option

Just Want the Numbers? useElementSize and useMeasure

Picking the Right Size Hook

Real Use Cases

SSR-Safe by Construction

Takeaways

React useObjectUrl Hook: Preview Files & Blobs Without Memory Leaks (2026)

React useObjectUrl Hook: Preview Files & Blobs Without Memory Leaks (2026)

The Manual Version, and Where It Leaks

useObjectUrl — Create and Revoke, Handled

When the Source Changes — and When It Unmounts

Real Use Cases

SSR-Safe by Construction

The File-Handling Trio

Takeaways

React useLocalStorage Hook: SSR-Safe Persistent State (2026)

React useLocalStorage Hook: SSR-Safe Persistent State (2026)

Why Not Just useState + useEffect?

useLocalStorage — useState That Survives Reloads

Objects, Maps, Sets, Dates — Serialization Is Automatic

Removing the Key: setValue(null)

SSR and Hydration, Actually Safe

In Sync Across Tabs — and Across Components

The Storage Family

Takeaways

React useReducedMotion Hook: Respect prefers-reduced-motion (2026)

React useReducedMotion Hook: Respect prefers-reduced-motion (2026)

The Naive Version

The API

Pattern 1: Kill a Single Animation

Pattern 2: Framer Motion / GSAP Integration

Pattern 3: One Global Switch Instead of N Guards

What "Reduce" Doesn't Mean

SSR Safety

The Preference-Query Family

Takeaways

React useIntersectionObserver Hook: Lazy Load & Detect Visibility (2026)

React useIntersectionObserver Hook: Lazy Load & Detect Visibility (2026)

Why Not Just Use a Scroll Listener?

The API

Pattern 1: Lazy-Load an Image

Pattern 2: Fire-Once "Viewed" Analytics

Pattern 3: Infinite-Scroll Trigger

Tuning: threshold, rootMargin, and root

The stop() Return Value

Just Want a Boolean?

SSR Safety

The Visibility & Size Family

Takeaways

React useDebounce Hook: Debounce State & Callbacks (2026)

Why Not Just Use setTimeout?

useDebounce — Debounce a Value

useDebounceFn — Debounce a Callback

cancel and flush in practice

Value or Callback — Which One?

Tuning: leading, trailing, and maxWait

SSR Safety

The Rate-Limiting Family

Takeaways

React useIsomorphicLayoutEffect: Fix the SSR useLayoutEffect Warning (2026)

Why useLayoutEffect Exists At All

Why the Server Hates It

Why You Can't Just Use useEffect

The Actual Fix: Branch on Environment

One subtlety: why the branch lives outside render

When To Reach For It (And When Not)

The Layout-Timing Family

Takeaways

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

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

The Bug, in One Component

1. useRafFn — The Loop, With Pause and Resume

2. useRafState — useState That Coalesces Per Frame

3. useFps — Measuring What You Built

4. useDevicePixelRatio — Drawing at the Right Resolution

The `box` Option