DEV Community: reactuse.com

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

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

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

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

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

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

1. usePreferredDark — The Boolean That Starts a Theme System

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

The Manual Way

import { useEffect, useState } from "react";

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

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

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

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

The ReactUse Way

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

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

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

2. usePreferredColorScheme — When "Dark" Is Not Enough

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

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

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

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

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

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

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

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

3. useColorMode — Theme State With Persistence

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

useColorMode is what you want for a real theme toggle:

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

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

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

With one hook you get:

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

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

4. useReducedMotion — The Cheapest Accessibility Win on the Web

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

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

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

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

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

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

Common places to wire it up:

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

5. usePreferredContrast — Boost the Edges When Asked

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

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

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

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

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

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

6. usePreferredLanguages — Beyond `navigator.language`

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

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

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

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

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

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

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

7. useTextDirection — RTL Is Not Just CSS

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

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

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

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

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

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

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

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

Putting It All Together: useAppearance

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

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

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

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

  const locale = pickLocale(preferred);

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

Use it once at the root:

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

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

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

CSS-First Where Possible, JS Where Necessary

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

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

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

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

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

Summary

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

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

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

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

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

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

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

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

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

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

The Manual Way

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

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

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

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

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

The ReactUse Way

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

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

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

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

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

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

2. useElementVisibility — The Boolean You Usually Want

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

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

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

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

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

3. useResizeObserver — The Right Way to Track Size

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

The Manual Way

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

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

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

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

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

The ReactUse Way

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

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

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

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

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

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

4. useElementSize and useMeasure — Size in Two Flavors

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

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

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

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

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

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

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

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

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

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

5. useElementBounding — Position Plus Size, Synced

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

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

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

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

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

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

6. useMutationObserver — When the DOM Changes Around You

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

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

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

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

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

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

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

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

7. Choosing Between Them

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

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

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

A Worked Example: A Self-Sizing Lazy Card

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

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

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

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

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

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

Performance Notes

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

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

Summary

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

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

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

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

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

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

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

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

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

1. The Tab Title as a Notification Channel

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

The Manual Way

import { useEffect, useState } from "react";

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

  return null;
}

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

The ReactUse Way: useTitle

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

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

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

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

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

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

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

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

2. State-Aware Favicons

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

The Manual Way

import { useEffect } from "react";

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

  return null;
}

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

The ReactUse Way: useFavicon

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

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

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

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

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

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

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

3. Pause Expensive Work When the Tab is Hidden

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

The Manual Way

import { useEffect, useState } from "react";

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

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

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

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

The ReactUse Way: useDocumentVisibility

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

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

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

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

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

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

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

4. Refresh on Focus

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

The Manual Way

import { useEffect, useState } from "react";

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

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

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

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

The ReactUse Way: useWindowsFocus

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

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

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

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

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

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

5. Catch the User Before They Leave

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

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

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

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

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

6. Native Notifications — Permission First

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

The two hooks that pair here are usePermission and useWebNotification.

Check the State Before You Ask

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

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

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

Ask Only on User Intent

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

Trigger the request from a button click instead:

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

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

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

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

Putting it All Together: An Attention-Aware Chat Tab

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

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

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

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

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

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

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

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

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

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

Summary

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

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

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

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

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

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

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

1. Debounced Async Validation

The Manual Way

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

import { useEffect, useState } from "react";

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

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

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

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

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

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

The ReactUse Way: useDebounce

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

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

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

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

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

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

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

2. Controlled or Uncontrolled — Pick One, Support Both

The Manual Way

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

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

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

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

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

The ReactUse Way: useControlled

useControlled collapses the whole pattern into a single hook call:

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

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

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

The hook does three things you would otherwise write yourself:

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

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

3. Auto-Saving Form Drafts

The Manual Way

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

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

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

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

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

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

The ReactUse Way: useLocalStorage

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

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

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

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

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

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

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

4. Closing Popovers with Click-Outside

The Manual Way

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

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

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

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

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

The ReactUse Way: useClickOutside

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

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

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

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

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

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

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

Putting It All Together: A Settings Form

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Four hooks, four responsibilities, zero overlap:

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

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

Installation

npm i @reactuses/core

Related Hooks

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

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

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

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

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

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

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

1. Live Speech Recognition

The Manual Way

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

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

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

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

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

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

The ReactUse Way: useSpeechRecognition

useSpeechRecognition returns a clean object with the right primitives:

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

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

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

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

Things you get for free:

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

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

2. Enumerating Cameras and Microphones

The Manual Way

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

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

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

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

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

The ReactUse Way: useMediaDevices

useMediaDevices packages the whole thing:

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

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

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

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

The hook handles three things you would otherwise write yourself:

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

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

3. Querying Permissions Properly

The Manual Way

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

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

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

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

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

The ReactUse Way: usePermission

usePermission reduces the entire dance to a single call:

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

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

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

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

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

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

4. Push-To-Talk With useKeyModifier

The Manual Way

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

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

  useEffect(() => {
    const onDown = (e: KeyboardEvent) => {
      if (e.code === "Space") setPressed(true);
    };
    const onUp = (e: KeyboardEvent) => {
      if (e.code === "Space") setPressed(false);
    };
    const onBlur = () => setPressed(false);
    window.addEventListener("keydown", onDown);
    window.addEventListener("keyup", onUp);
    window.addEventListener("blur", onBlur);
    return () => {
      window.removeEventListener("keydown", onDown);
      window.removeEventListener("keyup", onUp);
      window.removeEventListener("blur", onBlur);
    };
  }, []);

  return <p>{pressed ? "Recording..." : "Hold space to talk"}</p>;
}

This almost works. The bug: if the Space key auto-repeats while held (which it does on most operating systems), you will get a keydown followed by another keydown followed by an eventual keyup. You handled that. But if the user holds Shift instead and uses it as a modifier with another key combination, your manual tracking does not know about it.

The ReactUse Way: useKeyModifier

useKeyModifier exposes the OS-level modifier state (the same values you would get from event.getModifierState) as React state:

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

function ShiftToRecord({ onTalkStart, onTalkEnd }: {
  onTalkStart: () => void;
  onTalkEnd: () => void;
}) {
  const shift = useKeyModifier("Shift");

  useEffect(() => {
    if (shift) onTalkStart();
    else onTalkEnd();
  }, [shift, onTalkStart, onTalkEnd]);

  return (
    <div
      style={{
        padding: 16,
        background: shift ? "#fef3c7" : "#f1f5f9",
        borderRadius: 8,
        textAlign: "center",
      }}
    >
      {shift ? "Recording (release Shift to stop)" : "Hold Shift to talk"}
    </div>
  );
}

The benefits over the keydown/keyup version:

OS-aware. The hook reads getModifierState, which queries the actual modifier state from the OS. It survives auto-repeat, focus loss, and weird key combinations correctly.
Works for any modifier. Pass "Control", "Alt", "Meta", "CapsLock", "NumLock" -- anything the browser tracks as a modifier.
Initial value. Configure initial: true if you want the React state to start as true (uncommon but useful for debugging).

Putting It All Together: A Voice Search With Device Picker

We will combine all four hooks into a single voice-driven search component. The user can pick which microphone to use, sees a permission badge, holds Shift to start dictating, and watches the transcript update live as they speak. When they release Shift, the final transcript becomes the search query.

import { useEffect, useState } from "react";
import {
  useSpeechRecognition,
  useMediaDevices,
  usePermission,
  useKeyModifier,
} from "@reactuses/core";

function VoiceSearch() {
  const [selectedMic, setSelectedMic] = useState<string>("");
  const [query, setQuery] = useState("");

  const micPermission = usePermission("microphone");
  const [{ devices }, requestDevices] = useMediaDevices({
    requestPermissions: false,
    constraints: { audio: true, video: false },
  });

  const microphones = devices.filter((d) => d.kind === "audioinput");

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

  const shiftDown = useKeyModifier("Shift");

  // Push-to-talk: start when Shift is pressed, stop when released
  useEffect(() => {
    if (!isSupported || micPermission !== "granted") return;
    if (shiftDown) {
      start();
    } else if (isListening) {
      stop();
    }
  }, [shiftDown, isSupported, micPermission, start, stop, isListening]);

  // When recognition finalizes, commit the result to the query
  useEffect(() => {
    if (isFinal && result) {
      setQuery(result);
    }
  }, [isFinal, result]);

  const permissionColor =
    micPermission === "granted"
      ? "#10b981"
      : micPermission === "denied"
      ? "#ef4444"
      : "#f59e0b";

  return (
    <div
      style={{
        maxWidth: 640,
        padding: 24,
        background: "#ffffff",
        borderRadius: 16,
        boxShadow: "0 4px 24px rgba(15, 23, 42, 0.06)",
        fontFamily: "system-ui, sans-serif",
      }}
    >
      <header
        style={{
          display: "flex",
          justifyContent: "space-between",
          alignItems: "center",
          marginBottom: 16,
        }}
      >
        <h2 style={{ margin: 0, fontSize: 18 }}>Voice Search</h2>
        <span style={{ color: permissionColor, fontSize: 13, fontWeight: 600 }}>
          ● Mic: {micPermission || "unknown"}
        </span>
      </header>

      {!isSupported && (
        <p style={{ color: "#64748b" }}>
          This browser does not support speech recognition. Try Chrome.
        </p>
      )}

      {isSupported && micPermission !== "granted" && (
        <button
          onClick={requestDevices}
          style={{
            width: "100%",
            padding: 12,
            background: "#3b82f6",
            color: "white",
            border: "none",
            borderRadius: 8,
            cursor: "pointer",
          }}
        >
          Grant microphone access
        </button>
      )}

      {isSupported && micPermission === "granted" && (
        <>
          <div style={{ display: "flex", gap: 12, marginBottom: 12 }}>
            <select
              value={selectedMic}
              onChange={(e) => setSelectedMic(e.target.value)}
              style={{
                flex: 1,
                padding: 8,
                borderRadius: 6,
                border: "1px solid #cbd5e1",
              }}
            >
              <option value="">Default microphone</option>
              {microphones.map((mic) => (
                <option key={mic.deviceId} value={mic.deviceId}>
                  {mic.label || `Mic ${mic.deviceId.slice(0, 6)}`}
                </option>
              ))}
            </select>
          </div>

          <div
            style={{
              padding: 16,
              background: shiftDown ? "#dcfce7" : "#f8fafc",
              borderRadius: 8,
              border: shiftDown
                ? "2px solid #10b981"
                : "2px dashed #cbd5e1",
              textAlign: "center",
              transition: "all 120ms ease",
            }}
          >
            <p style={{ margin: 0, fontWeight: 600, fontSize: 13 }}>
              {shiftDown ? "Listening..." : "Hold Shift to dictate"}
            </p>
            {result && (
              <p
                style={{
                  margin: "8px 0 0",
                  fontStyle: isFinal ? "normal" : "italic",
                  color: isFinal ? "#0f172a" : "#64748b",
                }}
              >
                {result}
              </p>
            )}
          </div>

          {error && (
            <p style={{ color: "#ef4444", fontSize: 13, marginTop: 8 }}>
              Recognition error: {error.error}
            </p>
          )}

          <input
            value={query}
            onChange={(e) => setQuery(e.target.value)}
            placeholder="Search query..."
            style={{
              width: "100%",
              marginTop: 12,
              padding: 10,
              borderRadius: 6,
              border: "1px solid #cbd5e1",
              fontSize: 16,
            }}
          />
        </>
      )}
    </div>
  );
}

Four hooks, four orthogonal concerns:

usePermission drives the badge in the header and gates the rest of the UI behind the user's actual decision. Because it is reactive, if the user revokes mic access in browser settings, the badge updates and the input vanishes automatically.
useMediaDevices populates the microphone picker without forcing a permission prompt unless the user clicks "Grant".
useSpeechRecognition does the actual transcription, distinguishes interim from final results, and surfaces engine errors in a typed way.
useKeyModifier turns the Shift key into a push-to-talk trigger that survives focus loss, OS auto-repeat, and weird key combinations.

The component is roughly 130 lines, the vast majority of which is markup. The browser-API plumbing -- the parts that historically take the longest to get right -- is one import line per concern.

A Note on Testing

Voice and camera features are notoriously hard to test because the browser APIs they depend on require human gestures and physical hardware. The hooks all expose isSupported flags so your test environments (jsdom, Vitest, Storybook with mocked navigators) can branch cleanly on the absence of the underlying APIs and render fallback states. If you are building a serious voice UI, dedicate a small layer of integration tests that run in headless Chrome with a fake media stream -- that is the only way to catch the real bugs.

Installation

npm i @reactuses/core

Related Hooks

useSpeechRecognition -- Live speech-to-text with interim and final result tracking
useMediaDevices -- Enumerate cameras and microphones with permission handling
usePermission -- Reactively query the Permissions API for any permission name
useKeyModifier -- Track OS-level modifier key state (Shift, Control, etc.)
useSupported -- Reactively check whether a browser API is available
useEventListener -- Attach event listeners declaratively for custom voice flows
useObjectUrl -- Create temporary URLs for recorded audio blobs to preview them

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

The SSR State Management Trap: defineStore vs defineContextStore

reactuse.com — Wed, 06 May 2026 04:04:42 +0000

You ship a Next.js-style SSR app with a global user store. A month later, a user files a bug: "I logged in and saw someone else's profile." You can't reproduce it locally. Production logs are useless. The session cookie looks fine.

What happened: your global store is a singleton on the server. Under concurrent requests, one request's setUser() wrote to the same object another request was reading. The second user hit a warm server, got a hydration payload containing the first user's data, and saw it for a split second before React reconciled.

This is the SSR state management trap. It's one of the oldest footguns in server rendering, and almost every framework makes it possible. In this post: how it happens at the module level, how Pareto's defineStore and defineContextStore address it, and the decision rule for which one to use.

Why global state leaks across requests on the server

In the browser, your app is one process per user. A module-level variable is a per-user variable — there's no one else sharing it.

On the server, one Node process serves thousands of users. A module-level variable is shared across every request. If request A mutates it during its render, and request B reads it during its render, B sees A's state.

// state.ts (imported by server and client)
let currentUser = null

export function setCurrentUser(user) { currentUser = user }
export function getCurrentUser() { return currentUser }

Works in the browser. On the server, two requests racing through:

t=0ms:  Request A starts, calls setCurrentUser({ id: 'alice' })
t=1ms:  Request B starts, calls setCurrentUser({ id: 'bob' })
t=2ms:  Request A reads getCurrentUser() → { id: 'bob' }  ← leaked

Alice's rendered HTML contains Bob's name. Alice's hydration payload contains Bob's data. Whatever the server sends to Alice's browser now references Bob.

This doesn't require a state library. A global Map, a module.cache, a let declaration — all vulnerable. State libraries just dress up the same pattern.

What Pareto's two store types do

Pareto has two APIs that look almost identical but have opposite SSR behavior.

defineStore — one instance per process

import { defineStore } from '@paretojs/core/store'

const themeStore = defineStore((set) => ({
  mode: 'light' as 'light' | 'dark',
  toggle: () => set((d) => {
    d.mode = d.mode === 'light' ? 'dark' : 'light'
  }),
}))

On the server, there's one themeStore per Node process. Every SSR request reads and writes the same state. This is the dangerous primitive.

On the client, there's one themeStore per browser tab — which is what you actually want for client-side state.

defineContextStore — one instance per React render

import { defineContextStore } from '@paretojs/core/store'

const { Provider, useStore } = defineContextStore((initialUser) => (set) => ({
  user: initialUser,
  setUser: (user) => set((d) => { d.user = user }),
}))

Context stores are scoped to a <Provider>. Each SSR request renders its own provider tree, gets its own store instance, and can't see any other request's state.

function App({ user }) {
  return (
    <Provider initialData={user}>
      <Dashboard />
    </Provider>
  )
}

Two concurrent requests create two isolated stores. Alice's render never touches Bob's store. The pattern is guaranteed safe.

The decision rule

Ask: "Does the initial state of this store differ per user or per request?"

Yes — use defineContextStore. User identity, auth tokens, per-tenant config, feature flags that depend on the viewer, shopping cart tied to a session.
No — defineStore is fine. UI theme, sidebar open/closed, recently-viewed modals, client-side caches keyed on data that's already safe to share.

For the "no" case, the reasoning is: if every SSR request reads the same initial state, there's nothing for concurrent requests to leak to each other. The theme is 'light' for every new request until JavaScript hydrates and the client reads localStorage. No per-request state, no leak surface.

If you're ever unsure, pick defineContextStore. It's always safe. You can downgrade to defineStore later once you've confirmed the state is truly request-independent.

A leaky example and its fix

Here's a realistic pattern that leaks:

// ❌ Bad: user identity in a global store
import { defineStore } from '@paretojs/core/store'

export const userStore = defineStore((set) => ({
  user: null as User | null,
  setUser: (user: User) => set((d) => { d.user = user }),
  isAdmin: false,
}))

Then in a loader or layout:

// ❌ Mutating a global store during SSR
export async function loader(ctx: LoaderContext) {
  const user = await getUserFromSession(ctx.request)
  userStore.setState((d) => {
    d.user = user
    d.isAdmin = user.role === 'admin'
  })
  return { user }
}

This leaks in both directions. Concurrent requests overwrite d.user. Requests that arrive after a previous user's session read stale data. The bug looks like random user-mixup reports.

The fix:

// ✅ Good: context store, scoped to the render
import { defineContextStore } from '@paretojs/core/store'

export const { Provider: UserProvider, useStore: useUser } =
  defineContextStore((initial: { user: User; isAdmin: boolean }) => (set) => ({
    user: initial.user,
    isAdmin: initial.isAdmin,
    setUser: (user: User) => set((d) => { d.user = user }),
  }))

Wrap the app in a provider in the root layout:

// app/layout.tsx
import { UserProvider } from './stores/user'

export default function RootLayout({ children, loaderData }) {
  const { user, isAdmin } = loaderData as LoaderData
  return (
    <UserProvider initialData={{ user, isAdmin }}>
      {children}
    </UserProvider>
  )
}

Now every request gets its own store instance, initialized from its own loader data. No shared object. No leak path.

When defineStore is the right call

Not every store is dangerous. Plenty of client-state is genuinely the same on every SSR request and only diverges after hydration.

UI preferences

export const uiStore = defineStore((set) => ({
  sidebarOpen: true,
  commandPaletteOpen: false,
  toggleSidebar: () => set((d) => { d.sidebarOpen = !d.sidebarOpen }),
}))

On the server, every request starts with sidebarOpen: true. No user data, no request-dependent initial state. Safe.

Client-only feature toggles

export const devStore = defineStore((set) => ({
  showDebugOverlay: false,
  toggleDebugOverlay: () => set((d) => { d.showDebugOverlay = !d.showDebugOverlay }),
}))

Debug UI that only the developer uses. Initial state is identical for every request; all mutations happen on the client.

The "I'll just reset it at the start of each request" trick

A pattern people try when they realize globals leak: reset the store at the start of every SSR request.

// ❌ Doesn't work
export async function loader(ctx) {
  userStore.setState(() => ({ user: null, isAdmin: false }))
  const user = await getUserFromSession(ctx.request)
  userStore.setState((d) => { d.user = user })
  return { user }
}

This has two problems:

Reset and populate are not atomic. Another request can interleave between them and see the reset state — or the first request's populated state before its own reset.
Multiple renders share one store. Pareto's streaming SSR holds a response open while deferred promises resolve. During that window, another request can run through the same loader and overwrite the store.

The "reset per request" pattern is what AsyncLocalStorage exists to solve, and what context stores are in Pareto. Don't try to work around it with manual resets.

What about Zustand / Jotai / Redux?

Same principle. If the library's default API is a module-level store, it's unsafe on the server. Most of these libraries document an "SSR mode" that requires you to instantiate a per-request store and pass it through context.

Pareto's defineContextStore is that pattern as a first-class API. If you're coming from Zustand, defineContextStore is the shape you already know from Zustand's createStore + React context wrapper — just built in.

Pareto's defineStore is the global-singleton shortcut for cases where you've verified the shortcut is safe.

The bigger pattern

SSR adds a dimension most state management libraries weren't originally designed for. The browser gave you "one app, one state tree, forever." The server gives you "one process, many concurrent state trees, for a few milliseconds each." Any API that pretends these are the same will eventually leak.

Pareto's answer: two APIs with different defaults.

defineStore for state where "one process, one state" is genuinely what you want
defineContextStore for state where "each render tree, its own state" is what you need

Pick the one that matches the shape of the state. If you can't decide, defineContextStore is never wrong.

npx create-pareto@latest my-app
cd my-app && npm install && npm run dev

Pareto is a lightweight, streaming-first React SSR framework built on Vite. Documentation

Your Page Is Only as Fast as Your Slowest API: The Case for Streaming SSR

reactuse.com — Mon, 27 Apr 2026 02:35:36 +0000

You open Chrome DevTools on your product page. The Network tab has exactly one row that matters — the HTML document — and it's been stuck on "Waiting for response" for 1,400ms. From the browser's point of view, the server is a black box that hasn't said a word yet.

Pull up the server's APM trace and the black box opens up. Inside that 1.4 seconds, your loader fanned out to five upstream services:

Auth check — 30ms
Cart count — 50ms
Header navigation data — 80ms
Product details — 200ms
Personalized recommendations — 1,400ms

Time to first byte: 1,400ms. Time to first paint: 1,420ms. Every user, every page view, waits for the slowest API before the browser sees a single byte of HTML — even though four-fifths of the page's data was ready in 200ms.

This is the short-board effect, and almost every traditional SSR app pays it. The bucket fills to the height of the shortest plank. The page renders at the speed of the slowest dependency. Streaming SSR is the framework-level fix, and in 2026 it's no longer optional. Here's why.

The math: why this gets worse, not better

The short-board effect compounds with the number of data dependencies. Suppose each API in your loader has a 1% chance of running 5x slower than its median (cold cache, GC pause, network hiccup, dependency of a dependency timing out). With one API, your p99 page latency is fine. With five APIs, the probability that at least one is slow on a given request is:

1 - (1 - 0.01)^5 = 4.9%

With ten APIs it's 9.6%. The page p99 isn't the average of API p99 — it's the max. Adding a fast endpoint to your loader can't make the page faster, but adding a slow one always makes the page slower.

This is the architectural reality of every modern web app:

Pages depend on user data, content data, navigation data, A/B test buckets, feature flags, recommendations, ads, analytics consent, session state.
Each one is a separate service, often a separate team, often a separate company.
Slow dependencies rarely get removed. They just get added to.
Personalized data can't be cached.
Real-time data can't be cached.
The CDN can't help — the response is per-user.

If your page has any external dependency you don't fully control, you have a slowest-API problem. The question is what you do about it.

What traditional SSR does

The standard SSR loader pattern is Promise.all:

export async function loader() {
  const [user, nav, product, recs] = await Promise.all([
    getUser(),         // 30ms
    getNav(),          // 80ms
    getProduct(),      // 200ms
    getRecs(),         // 1400ms ← waits for this
  ])
  return { user, nav, product, recs }
}

The render function gets called once, with all data resolved. The HTML is generated in one pass. The response body starts flowing only after the slowest fetch returns.

From the user's perspective:

TTFB: 1,400ms (waiting for recs)
First paint: ~1,420ms (TTFB + parse)
Largest contentful paint: ~1,450ms

The user is staring at a blank tab for 1.4 seconds. The browser hasn't even started parsing HTML, because the server hasn't sent any. Adding a CDN doesn't help — the document itself is slow. Adding more bandwidth doesn't help — the bottleneck is server-side compute waiting on I/O.

Why "just fetch on the client" isn't the answer

The first instinct for many teams is: render the shell server-side, fetch the slow data after hydration. This trades one problem for two.

Waterfall: HTML → CSS → JS → hydrate → fetch → render. Each step blocks the next. On a slow network, the time-to-interactive for the slow section is even higher than it was server-side, because the client now has to download and parse JS first.

SEO: Search crawlers read what's in the HTML. Recommendations rendered after hydration aren't in the initial document. For pages where the slow data is the important data — product reviews, comparison tables, location-specific content — client fetching makes the page invisible to ranking signals.

Client-side fetching is sometimes the right call (deeply interactive widgets, viewport-triggered loads), but it's not a fix for the slowest-API problem. It just hides the latency behind a loading spinner that the user has to wait through anyway.

Why caching alone isn't the answer

"Cache it" is the second instinct. Caching helps, and you should do it. But it doesn't solve the architectural problem:

Cold caches happen. Every deploy. Every cache eviction. Every key miss. The first user after a flush still pays full latency.
Personalized data can't be cached. Or can be cached only per-user, with hit rates that hover near zero on long-tail traffic.
Real-time data can't be cached. Inventory, prices, live scores, chat presence — caching them is the bug.
Stale data is its own bug. Aggressive caching ships wrong information. Conservative caching loses most of the benefit.

Streaming SSR composes with caching. You cache what you can, you stream what you can't. The two strategies aren't alternatives — they target different problems.

What streaming SSR actually does

Streaming SSR breaks the all-or-nothing render. The server sends two kinds of data in one response:

The shell + fast data — flushed to the client immediately, while slow fetches are still in flight.
The slow data — streamed in as Suspense fallbacks resolve, written to the same response body in chunks.

The browser starts parsing HTML as soon as the first chunk arrives. CSS and fonts kick off in parallel with the rest of the document. By the time the slow API returns, the user has already been reading the page for a second.

// app/product/loader.ts
import { defer } from '@paretojs/core'

export async function loader(ctx) {
  const [user, nav, product] = await Promise.all([
    getUser(ctx),     // 30ms
    getNav(ctx),      // 80ms
    getProduct(ctx),  // 200ms
  ])

  return defer({
    user, nav, product,           // resolved — included in shell
    recs: getRecs(ctx),           // promise — streams when ready
  })
}

// app/product/page.tsx
import { Await } from '@paretojs/core'
import { Suspense } from 'react'

export default function ProductPage({ data }) {
  return (
    <>
      <Header user={data.user} nav={data.nav} />
      <ProductDetail product={data.product} />

      <Suspense fallback={<RecsSkeleton />}>
        <Await resolve={data.recs}>
          {(recs) => <Recommendations items={recs} />}
        </Await>
      </Suspense>
    </>
  )
}

From the user's perspective now (assuming ~40ms RTT to the nearest edge):

TTFB: ~240ms — RTT plus the slowest fetch you still await in the loader (product, 200ms). The shell flushes the moment that resolves; recs is still in flight.
First paint: ~290ms after the document parses
Header, nav, product: visible at ~290ms
Recommendations: stream in around 1,440ms — but the user has been reading the page for over a second already

Same total work. Same backend latency. Completely different user experience. The slow API no longer holds the rest of the page hostage.

A concrete numbers table

Same product page, same APIs, two render strategies:

Metric	Traditional SSR	Streaming SSR
TTFB	~1,440ms (RTT + slowest fetch)	~240ms (RTT + slowest awaited fetch)
First paint	~1,460ms	~290ms
Above-the-fold visible	~1,460ms	~290ms
Recommendations visible	~1,460ms	~1,440ms
Bytes to first byte	full page	shell only
SEO	full page	full page (slow data still in HTML, just later in the stream)
Backend cost	identical	identical

Streaming SSR doesn't fix layout shift — that's on you. A <Suspense> fallback whose rendered height doesn't match the real content jumps just as hard as a client-side skeleton would. Budget the height (fixed min-height, aspect-ratio boxes, skeleton lines that match line counts) and CLS stays clean.

That last column is the important one. Streaming SSR doesn't make the slow API faster. It just stops it from blocking the rest of the page. The fix is structural, not performance-magic.

Why this is the new default

In 2024, streaming SSR was a power-user feature. In 2026, it's table stakes. Every serious React framework supports it: Next.js (via RSC + Suspense), Remix and React Router (via defer() and <Await>), TanStack Start, Pareto. The reason isn't fashion — it's that the alternative is shipping a page that's measurably worse for everyone whose backend has more than one dependency. Which is everyone.

The remaining decision isn't "should I use streaming SSR." It's "which abstraction do I want to use to do it." React Server Components are one answer — they bring streaming, but they also bring "use client", the dual-component model, and a lot of mental overhead about which code runs where. The other answer is the loader-plus-defer() model: ordinary React components, ordinary Suspense boundaries, one extra primitive in your loader. Pareto picks the second path. The result is roughly 1/4 the client JS of a Next.js equivalent and none of the RSC mental tax — but the streaming behavior is the same, because that's what the response actually does on the wire.

What to actually do

If you have an existing SSR app, the migration is mechanical and incremental:

Find your slow APIs. Look at p95 of every fetch in your loaders. Anything past 200ms is a candidate.
Move the slow ones into defer(). Don't await them in the loader. Pass the promise.
Wrap their consumer in <Suspense> + <Await>. Provide a fallback that reserves the right amount of space.
Measure TTFB and FCP. They should drop to roughly your RTT plus the slowest fetch you still await in the loader — not the slowest fetch overall.

You're not rewriting the page. You're cutting the wire that ties the fast paint to the slow data.

npx create-pareto@latest my-app
cd my-app && npm install && npm run dev

head.tsx Is Just a React Component: Dynamic SEO Meta from Loader Data

reactuse.com — Tue, 21 Apr 2026 03:41:24 +0000

Look at how most frameworks handle <head>:

// Next.js
export const metadata = {
  title: 'Blog Post',
  description: '...',
  openGraph: { title: '...', images: [...] },
}

// Remix
export const meta: MetaFunction = ({ data }) => [
  { title: 'Blog Post' },
  { name: 'description', content: '...' },
  { property: 'og:image', content: data.post.coverImage },
]

Metadata is a config object. You shape strings and key-value pairs into whatever schema the framework prescribed, and the framework turns them into HTML tags.

Pareto does something different. In Pareto, head.tsx is a React component that returns JSX:

// app/head.tsx
export default function Head() {
  return (
    <>
      <title>My App</title>
      <meta name="description" content="My awesome app." />
    </>
  )
}

That's it. No config schema to learn. No special MetaDescriptor type. You write <title> and <meta> tags, and React 19 hoists them into the document <head>.

This post is about why that's a better design, and what it unlocks — especially for dynamic SEO where the meta tags depend on data you fetched on the server.

Why a component is better than a config

Three reasons, in order of importance.

1. You get JSX — including expressions, loops, and conditionals

A config object is static data. If you want "include this meta tag only when the user has a premium account," you end up building the object imperatively before returning it, or stuffing conditional logic into values.

A component is code. You express conditions the normal way:

export default function Head({ loaderData }: HeadProps) {
  const data = loaderData as LoaderData
  return (
    <>
      <title>{data.product.name}</title>
      <meta name="description" content={data.product.tagline} />

      {data.product.coverImage && (
        <meta property="og:image" content={data.product.coverImage} />
      )}

      {data.product.keywords.map((kw) => (
        <meta property="article:tag" content={kw} key={kw} />
      ))}

      {data.product.isPaid && (
        <meta property="og:restricted" content="paywall" />
      )}
    </>
  )
}

Loops, guards, conditional rendering — everything React already does. No metadataProvider, no generateMetadata signature to remember. It's just JSX.

2. Head components compose like the rest of your app

Want to pull shared OG tags into a helper? It's a React component:

function OpenGraphTags({ title, description, image }: OGProps) {
  return (
    <>
      <meta property="og:title" content={title} />
      <meta property="og:description" content={description} />
      <meta property="og:image" content={image} />
      <meta property="og:type" content="article" />
    </>
  )
}

export default function Head({ loaderData }: HeadProps) {
  const { post } = loaderData as { post: Post }
  return (
    <>
      <title>{post.title} — My Blog</title>
      <meta name="description" content={post.excerpt} />
      <OpenGraphTags
        title={post.title}
        description={post.excerpt}
        image={post.coverImage}
      />
    </>
  )
}

In a config-object world, this is a helper function that returns an array that you spread into another array. Here, it's a component. Read the tree and you see the HTML that will end up in <head>.

3. React 19 does the hoisting for you

This is the feature that makes the whole thing work. In React 19, any <title>, <meta>, or <link> tag you render anywhere in the tree gets hoisted into the document <head> — both during SSR and during client-side navigation. There's no framework-specific MetaProvider collecting and serializing metadata. It's a React platform feature.

Pareto doesn't implement the hoisting. React does. Pareto just decides where to render your head.tsx component in the tree (between root and page) so the hoisting has something to pick up.

The route tree determines what wins

Head components render from root to page. Each level contributes tags. When two levels render the same tag (say, two <title>s), the browser uses the last one — so the deepest route wins automatically.

app/
  head.tsx                  ← site defaults
  blog/
    head.tsx                ← overrides for /blog section
    [slug]/
      head.tsx              ← overrides for individual posts

The root sets defaults. The section level overrides them. The leaf route overrides again. This matches how you actually think about SEO — most tags are site-wide, a section diverges a little, and individual pages add their own specifics.

// app/head.tsx — site defaults
export default function Head() {
  return (
    <>
      <title>My App</title>
      <meta name="description" content="The best app for doing things." />
      <link rel="icon" href="/favicon.ico" />
      <meta property="og:site_name" content="My App" />
      <meta name="twitter:card" content="summary_large_image" />
    </>
  )
}

// app/blog/[slug]/head.tsx — overrides for individual posts
import type { HeadProps } from '@paretojs/core'

export default function Head({ loaderData }: HeadProps) {
  const { post } = loaderData as { post: BlogPost }
  return (
    <>
      <title>{post.title} — My App</title>
      <meta name="description" content={post.excerpt} />
      <meta property="og:title" content={post.title} />
      <meta property="og:description" content={post.excerpt} />
      <meta property="og:type" content="article" />
      <meta property="og:image" content={post.coverImage} />
      <meta property="article:published_time" content={post.publishedAt} />
      <meta property="article:author" content={post.author.name} />
      <link rel="canonical" href={`https://myapp.com/blog/${post.slug}`} />
    </>
  )
}

The final <head> for /blog/hello-world merges both: favicon and twitter defaults from root, title and every OG-specific tag from the post's head.tsx.

Same pattern, just a component tree. No metadataMerge function, no deep-merge semantics to learn.

HeadProps: loader data, typed

Every head component receives two props:

interface HeadProps {
  loaderData: unknown
  params: Record<string, string>
}

loaderData is whatever that route's loader returned. It's typed unknown because head.tsx has no way to know your loader's schema at runtime — cast it to your actual type:

export default function Head({ loaderData, params }: HeadProps) {
  const { post } = loaderData as { post: BlogPost }
  return <title>{post.title}</title>
}

This is the piece that makes dynamic SEO fall into place. The loader fetched the post. The head component gets the exact same data. Writing <meta property="og:title" content={post.title} /> uses the same object.

No separate generateMetadata call that re-fetches the post. The data flows: loader → page + head, both render with the same result.

A complete dynamic SEO example

Here's what shipping real per-page SEO for a product catalog looks like.

// app/products/[id]/loader.ts
import type { LoaderContext } from '@paretojs/core'

export async function loader(ctx: LoaderContext) {
  const product = await db.product.findUnique({
    where: { id: ctx.params.id },
    include: { images: true, category: true },
  })

  if (!product) {
    throw new Response('Not found', { status: 404 })
  }

  return { product }
}

// app/products/[id]/head.tsx
import type { HeadProps } from '@paretojs/core'

interface Product {
  id: string
  name: string
  description: string
  price: number
  currency: string
  images: { url: string }[]
  inStock: boolean
}

export default function Head({ loaderData }: HeadProps) {
  const { product } = loaderData as { product: Product }
  const canonicalUrl = `https://shop.example.com/products/${product.id}`
  const primaryImage = product.images[0]?.url ?? '/default-og.png'

  const jsonLd = {
    '@context': 'https://schema.org',
    '@type': 'Product',
    name: product.name,
    description: product.description,
    image: product.images.map((img) => img.url),
    offers: {
      '@type': 'Offer',
      price: product.price,
      priceCurrency: product.currency,
      availability: product.inStock
        ? 'https://schema.org/InStock'
        : 'https://schema.org/OutOfStock',
      url: canonicalUrl,
    },
  }

  return (
    <>
      <title>{`${product.name} — Our Shop`}</title>
      <meta name="description" content={product.description} />
      <link rel="canonical" href={canonicalUrl} />

      <meta property="og:type" content="product" />
      <meta property="og:title" content={product.name} />
      <meta property="og:description" content={product.description} />
      <meta property="og:image" content={primaryImage} />
      <meta property="og:url" content={canonicalUrl} />
      <meta property="product:price:amount" content={String(product.price)} />
      <meta property="product:price:currency" content={product.currency} />

      <meta name="twitter:card" content="summary_large_image" />
      <meta name="twitter:title" content={product.name} />
      <meta name="twitter:description" content={product.description} />
      <meta name="twitter:image" content={primaryImage} />

      <script
        type="application/ld+json"
        dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
      />
    </>
  )
}

One file. Dynamic title, full Open Graph, Twitter cards, canonical URL, and JSON-LD structured data — all derived from the same product object the page component uses. No duplicate fetches. No separate metadata API.

Inline scripts that must run before paint

Occasionally you need a script to execute before the page paints — the classic example is setting a dark-mode class on <html> based on localStorage, so the user doesn't see a flash of the wrong theme.

Inline scripts work inside head.tsx:

export default function Head() {
  return (
    <>
      <title>My App</title>
      <script
        dangerouslySetInnerHTML={{
          __html: `(function(){
            try {
              var t = localStorage.getItem('theme');
              if (t === 'dark' || (!t && matchMedia('(prefers-color-scheme:dark)').matches))
                document.documentElement.classList.add('dark')
            } catch(e) {}
          })()`,
        }}
      />
    </>
  )
}

One caveat: React 19 hoists <title>, <meta>, and <link> during client-side navigation, but not <script> tags. This is fine for initialization scripts that only need to run once on page load.

The shorter story

Pareto's head system is a convention on top of a React 19 feature:

head.tsx is a React component that returns JSX
React 19 hoists <title>, <meta>, <link> into <head> automatically
Head components receive loaderData and params as props
The tree renders root-to-page; the last tag of a given kind wins

There's no separate metadata API to learn. If you know React, you know how to write meta tags. For anything dynamic — blog posts, product pages, user profiles, search results — the pattern is always the same: loader returns the data, head.tsx renders JSX that uses it, React 19 hoists the tags. SEO shipped.

npx create-pareto@latest my-app
cd my-app && npm install && npm run dev

Pareto is a lightweight, streaming-first React SSR framework built on Vite. Documentation

Dynamic Routes in Pareto: [slug], Catch-All, and Nested Layouts

reactuse.com — Thu, 16 Apr 2026 08:53:12 +0000

File-based routing is one of those features that feels trivial until you try to build something non-trivial with it. Dynamic blog slugs, multi-level doc paths, tenant dashboards with shared sidebars, marketing pages that share a layout but not a URL prefix — every real app needs all of these, and every router handles them slightly differently.

This post walks through every routing pattern Pareto supports, with examples you can copy directly into your app/ folder.

The mental model

In Pareto, the file system is the router. Every directory under app/ that contains a page.tsx becomes a URL. There's no separate route config, no routes.ts registry, no code generation step. You move a file — the URL changes. You rename a directory — the URL changes.

The whole convention set:

File	What it does
`page.tsx`	Renders the page
`layout.tsx`	Wraps child pages
`loader.ts`	Server-side data fetching
`head.tsx`	`<title>`, meta tags
`not-found.tsx`	404 page (root only)
`error.tsx`	Error page (root only)
`document.tsx`	`<html>` customization (root only)
`route.ts`	JSON API endpoint

Everything else you can put in a folder is just colocated components, utilities, or stylesheets that Pareto ignores.

Static routes

The simplest case:

app/
  page.tsx              → /
  about/
    page.tsx            → /about
  pricing/
    page.tsx            → /pricing
  blog/
    page.tsx            → /blog

Directory names become URL segments, one-to-one. Capitalization matters — app/About/page.tsx produces /About, not /about. Stick to lowercase.

Dynamic segments: [param]

Most real apps have at least one page that takes a dynamic parameter — a blog slug, a product ID, a username. Wrap the segment in brackets:

app/blog/[slug]/page.tsx  → /blog/:slug

This route matches /blog/hello-world, /blog/pareto-4, /blog/anything-at-all. You access the value through ctx.params:

// app/blog/[slug]/loader.ts
import type { LoaderContext } from '@paretojs/core'

export async function loader(ctx: LoaderContext) {
  const { slug } = ctx.params
  const post = await db.post.findUnique({ where: { slug } })

  if (!post) {
    throw new Response('Not found', { status: 404 })
  }

  return { post }
}

The param key inside the brackets is the key on ctx.params. Name it [slug], get params.slug. Name it [id], get params.id. There's no magic mapping.

You can combine multiple dynamic segments:

app/users/[userId]/posts/[postId]/page.tsx  → /users/:userId/posts/:postId

Both params show up in ctx.params:

const { userId, postId } = ctx.params

Catch-all routes: [...param]

Sometimes you don't know how deep a path will go. A docs site might have /docs/getting-started, /docs/api/core/loader, /docs/guides/deployment/docker/rootless. Writing a folder for every depth is absurd. Use a catch-all:

app/docs/[...path]/page.tsx  → /docs/*

ctx.params.path contains everything after /docs/ as a single string with slashes preserved:

// /docs/getting-started       → path = "getting-started"
// /docs/api/core/loader       → path = "api/core/loader"
// /docs/guides/deploy/docker  → path = "guides/deploy/docker"

Split it however you want:

// app/docs/[...path]/page.tsx
import { useLoaderData } from '@paretojs/core'

export default function DocsPage() {
  const { doc } = useLoaderData<{ doc: { title: string; html: string } }>()
  return (
    <article>
      <h1>{doc.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: doc.html }} />
    </article>
  )
}

// app/docs/[...path]/loader.ts
export async function loader(ctx: LoaderContext) {
  const slug = ctx.params.path  // "api/core/loader"
  const doc = await loadMarkdown(`content/docs/${slug}.md`)
  return { doc }
}

Optional catch-all: [[...param]]

The gotcha with [...path]: it does not match the parent path. /docs/[...path]/page.tsx matches /docs/anything but not /docs itself — visiting /docs gives you a 404.

If you want both the parent and the children to render the same component, use a double-bracket optional catch-all:

app/docs/[[...path]]/page.tsx  → /docs AND /docs/*

At the root, ctx.params.path is undefined. Check for it:

export async function loader(ctx: LoaderContext) {
  const slug = ctx.params.path ?? 'index'
  const doc = await loadMarkdown(`content/docs/${slug}.md`)
  return { doc }
}

Now /docs loads content/docs/index.md and /docs/api/core loads content/docs/api/core.md. One route file covers the whole tree.

Nested layouts

Layouts are the reason you don't repeat your header and footer in every page. A layout.tsx wraps every page in its directory and below:

app/
  layout.tsx            ← wraps everything
  page.tsx              ← /
  dashboard/
    layout.tsx          ← wraps dashboard pages
    page.tsx            ← /dashboard
    settings/
      page.tsx          ← /dashboard/settings
    billing/
      page.tsx          ← /dashboard/billing

The render tree for /dashboard/settings:

<RootLayout>
  <DashboardLayout>
    <SettingsPage />
  </DashboardLayout>
</RootLayout>

Layouts receive their children as a prop:

// app/dashboard/layout.tsx
import type { PropsWithChildren } from 'react'
import { Link } from '@paretojs/core'

export default function DashboardLayout({ children }: PropsWithChildren) {
  return (
    <div className="dashboard-shell">
      <aside>
        <Link to="/dashboard">Overview</Link>
        <Link to="/dashboard/settings">Settings</Link>
        <Link to="/dashboard/billing">Billing</Link>
      </aside>
      <main>{children}</main>
    </div>
  )
}

Navigate between /dashboard, /dashboard/settings, /dashboard/billing — the sidebar never unmounts. Only the page content inside <main> changes. This is the nested-layout win: stable UI shells across related routes, without Redux-for-the-sidebar workarounds.

Route groups: share a layout without a URL segment

You'll often want to share a layout between routes that don't share a URL prefix. Marketing pages (/, /about, /pricing) want one layout. Auth pages (/login, /signup) want a different layout. Neither wants the layout name in the URL.

Wrap directories in parentheses to make them route groups — they affect layout nesting but disappear from the URL:

app/
  (marketing)/
    layout.tsx          ← shared marketing layout
    page.tsx            → /
    about/
      page.tsx          → /about
    pricing/
      page.tsx          → /pricing
  (auth)/
    layout.tsx          ← shared auth layout (centered card, no nav)
    login/
      page.tsx          → /login
    signup/
      page.tsx          → /signup

No URL contains the word marketing or auth. The parentheses vanish at build time — they're purely a grouping mechanism for the file tree.

A realistic example: multi-tenant SaaS

Let's put everything together. You're building a SaaS where each tenant has their own dashboard at /t/:tenantSlug, with a docs site, public marketing pages, and auth pages. Here's the full tree:

app/
  layout.tsx                        ← root layout (theme, fonts)

  (marketing)/
    layout.tsx                      ← marketing shell
    page.tsx                        → /
    pricing/
      page.tsx                      → /pricing
    about/
      page.tsx                      → /about

  (auth)/
    layout.tsx                      ← centered auth card
    login/
      page.tsx                      → /login
    signup/
      page.tsx                      → /signup

  t/
    [tenantSlug]/
      layout.tsx                    ← tenant shell (sidebar, tenant switcher)
      loader.ts                     ← load tenant, 404 if missing
      page.tsx                      → /t/:tenantSlug (overview)
      settings/
        page.tsx                    → /t/:tenantSlug/settings
      projects/
        [projectId]/
          layout.tsx                ← project shell
          page.tsx                  → /t/:tenantSlug/projects/:projectId

  docs/
    [[...path]]/
      page.tsx                      → /docs AND /docs/*
      loader.ts

  api/
    health/
      route.ts                      → /api/health (JSON)

Every pattern from this post is in there:

Route groups (marketing) and (auth) for URL-free layout sharing
Dynamic params [tenantSlug], [projectId]
Optional catch-all [[...path]] for docs
Nested layouts at root, tenant, and project level
A route.ts for a JSON health endpoint

The root layout.tsx handles theme, fonts, and global providers. The tenant layout runs a loader that fetches the tenant record and throws a 404 if the slug is invalid — every page inside automatically gets the check. The project layout adds project-level navigation. No page inside /t/:tenantSlug/* has to re-fetch the tenant or re-render the sidebar.

Loader precedence: page.tsx vs loader.ts

You can export a loader from page.tsx:

// app/blog/[slug]/page.tsx
export function loader(ctx: LoaderContext) {
  return { post: getPost(ctx.params.slug) }
}

export default function BlogPost() { /* ... */ }

Or put it in a separate file:

// app/blog/[slug]/loader.ts
export function loader(ctx: LoaderContext) {
  return { post: getPost(ctx.params.slug) }
}

If both exist, loader.ts wins. Use the separate file when your loader has heavy server-only dependencies (database drivers, file system calls, secret env vars) — keeping them out of page.tsx prevents accidental imports in client code paths.

For tiny loaders, inlining in page.tsx is fine. For anything involving a DB client, use loader.ts.

Route matching: specificity beats source order

When a URL could match multiple routes, Pareto picks the most specific one. Specificity rules:

Static segments beat dynamic segments
Dynamic segments beat catch-all segments
Required catch-all beats optional catch-all

So for /blog/featured:

app/blog/featured/page.tsx — static, wins
app/blog/[slug]/page.tsx — dynamic, loses to static
app/blog/[...rest]/page.tsx — catch-all, loses to dynamic

This means you can freely mix specific routes alongside dynamic ones. Define /blog/featured as a special static page, and every other slug falls through to /blog/[slug]. No conditional rendering inside the dynamic component, no matching priority to configure.

What's not in the router

Pareto's router is deliberately smaller than Next.js's. Things it doesn't have:

No parallel routes. One slot per layout. If you need two independently-routed panes, compose them with React state or multiple <iframe> boundaries.
No intercepting routes. Modals that want a URL are just modals with URL state — use a query param or a [modal] dynamic segment.
No middleware file convention. Do auth checks in layout loaders (they run for every nested page) or in the Hono app config.
No private folder convention. Just name your non-route files whatever you want. If there's no page.tsx, it's not a route.

The upside: there's almost nothing to memorize. The whole routing system fits in one doc page and this blog post.

Try it

npx create-pareto@latest my-app
cd my-app && npm install && npm run dev

Start with a single page.tsx. Add a [slug] when you need one. Reach for route groups when your layouts diverge. The router will keep up with whatever shape your app grows into.

Pareto is a lightweight, streaming-first React SSR framework built on Vite. Documentation

Building Immersive Web Apps in React: Fullscreen, Wake Lock, and Notifications

reactuse.com — Wed, 15 Apr 2026 03:28:24 +0000

Building Immersive Web Apps in React: Fullscreen, Wake Lock, and Notifications

The web has quietly grown into a real application platform. A reading app should be able to dim the chrome and fill the screen. A video player should keep the screen awake while playing. A timer should buzz the user even when the tab is in the background. A recipe app should respect the curve of an iPhone's notch and the home indicator at the bottom. None of these are exotic features anymore -- they are baseline expectations -- yet wiring each one up in React is its own small adventure of vendor prefixes, permission flows, lifecycle gotchas, and SSR landmines.

This post walks through six browser capabilities that turn a React app from "page in a browser" into something that feels like an installed application: entering and exiting fullscreen, keeping the screen awake during long tasks, sending OS-level notifications, respecting safe area insets on notched devices, and updating the title and favicon to reflect application state. As always, we will start each section with the manual implementation so you understand what is happening, then swap it out for a focused hook from ReactUse. At the end, we will combine all six into a focus-mode reading view that goes fullscreen, locks the screen awake, pings the user with a notification when they have been reading too long, and respects the device's safe area.

1. Fullscreen Without the Vendor Prefixes

The Manual Way

The Fullscreen API is one of the oldest examples of why feature detection is hard. Different browsers exposed requestFullscreen, webkitRequestFullscreen, mozRequestFullScreen, and msRequestFullscreen -- and a corresponding tangle of fullscreenchange, webkitfullscreenchange, mozfullscreenchange, MSFullscreenChange events. Even in 2026 the prefixes have not entirely faded:

function ManualFullscreen() {
  const [isFullscreen, setIsFullscreen] = useState(false);
  const elementRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const handleChange = () => {
      const fsEl =
        document.fullscreenElement ||
        (document as any).webkitFullscreenElement ||
        (document as any).mozFullScreenElement ||
        (document as any).msFullscreenElement;
      setIsFullscreen(Boolean(fsEl));
    };
    const events = [
      "fullscreenchange",
      "webkitfullscreenchange",
      "mozfullscreenchange",
      "MSFullscreenChange",
    ];
    events.forEach((e) => document.addEventListener(e, handleChange));
    return () =>
      events.forEach((e) => document.removeEventListener(e, handleChange));
  }, []);

  const enter = () => {
    const el = elementRef.current as any;
    if (!el) return;
    (
      el.requestFullscreen ||
      el.webkitRequestFullscreen ||
      el.mozRequestFullScreen ||
      el.msRequestFullscreen
    )?.call(el);
  };

  const exit = () => {
    const doc = document as any;
    (
      doc.exitFullscreen ||
      doc.webkitExitFullscreen ||
      doc.mozCancelFullScreen ||
      doc.msExitFullscreen
    )?.call(doc);
  };

  return (
    <div ref={elementRef}>
      <button onClick={isFullscreen ? exit : enter}>
        {isFullscreen ? "Exit fullscreen" : "Go fullscreen"}
      </button>
    </div>
  );
}

This works. It is also forty lines of casts, optional chaining, and prefix juggling, none of which add value to the feature you actually wanted. And it is silently incomplete -- it does not detect when the browser cannot enter fullscreen at all (locked-down kiosks, embedded iframes without allow="fullscreen", etc.), so your button just appears to do nothing.

The ReactUse Way: useFullscreen

useFullscreen wraps the screenfull library underneath and gives you a single tuple:

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

function FullscreenViewer() {
  const ref = useRef<HTMLDivElement>(null);
  const [isFullscreen, { toggleFullscreen, isEnabled }] = useFullscreen(ref, {
    onEnter: () => console.log("Entered fullscreen"),
    onExit: () => console.log("Exited fullscreen"),
  });

  if (!isEnabled) {
    return <p>Fullscreen is not available in this environment.</p>;
  }

  return (
    <div
      ref={ref}
      style={{
        background: isFullscreen ? "#000" : "#f1f5f9",
        color: isFullscreen ? "#fff" : "#0f172a",
        padding: 40,
        minHeight: 200,
      }}
    >
      <h2>{isFullscreen ? "Focus Mode" : "Click to enter focus mode"}</h2>
      <button onClick={toggleFullscreen}>
        {isFullscreen ? "Exit" : "Enter"} fullscreen
      </button>
    </div>
  );
}

A few things worth pointing out:

isEnabled tells you whether fullscreen is even possible in the current context. If you are in an iframe without permission, you can render a fallback instead of a button that lies.
onEnter/onExit callbacks let you play a sound, dim other UI, or fire analytics without managing your own listeners.
toggleFullscreen is stable across renders (the hook uses useEvent internally), so you can pass it to memoized children without invalidation.

The same pattern works for any element: a video, an article, an editor pane. Just pass the ref and you get the full lifecycle for free.

2. Keeping the Screen Awake

The Manual Way

The Screen Wake Lock API is the right tool for any flow where the user is watching, listening, reading, or otherwise not touching the screen for a while. Without it, mobile devices will dim and lock after the OS-defined timeout. With it, you can request a sentinel that keeps the screen on while you hold it.

The catch is that wake locks can be released by the system at any time, and they must be re-requested when the page becomes visible again -- if a user backgrounds your tab and then comes back, you have to ask for the lock all over again, or the screen will start dimming.

function ManualWakeLock() {
  const sentinelRef = useRef<WakeLockSentinel | null>(null);
  const [active, setActive] = useState(false);

  useEffect(() => {
    if (!("wakeLock" in navigator)) return;

    const request = async () => {
      try {
        sentinelRef.current = await navigator.wakeLock.request("screen");
        setActive(true);
        sentinelRef.current.addEventListener("release", () => setActive(false));
      } catch (e) {
        console.error("Wake lock failed:", e);
      }
    };

    const handleVisibility = () => {
      if (
        document.visibilityState === "visible" &&
        sentinelRef.current === null
      ) {
        request();
      }
    };

    request();
    document.addEventListener("visibilitychange", handleVisibility);

    return () => {
      sentinelRef.current?.release();
      document.removeEventListener("visibilitychange", handleVisibility);
    };
  }, []);

  return <span>Screen lock: {active ? "on" : "off"}</span>;
}

This is correct, but you have already encoded three subtle things: feature detection for 'wakeLock' in navigator, the request flow with try/catch, and the visibility-change re-request. Miss any of them and the lock silently stops working in the wild.

The ReactUse Way: useWakeLock

useWakeLock returns a small object with five members and handles the visibility dance for you:

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

function VideoPlayer({ playing }: { playing: boolean }) {
  const { isSupported, isActive, request, release } = useWakeLock({
    onRequest: () => console.log("Wake lock acquired"),
    onRelease: () => console.log("Wake lock released"),
    onError: (e) => console.error(e),
  });

  useEffect(() => {
    if (!isSupported) return;
    if (playing) request();
    else release();
  }, [playing, isSupported, request, release]);

  return (
    <p>
      {isSupported
        ? `Wake lock is ${isActive ? "active" : "idle"}`
        : "Wake lock not supported in this browser"}
    </p>
  );
}

What you get without writing it:

Visibility re-request. If the user backgrounds your tab while a video is playing and then comes back, the lock is automatically reacquired.
Suspended request. If you call request() while the page is hidden, the hook remembers and acquires it the moment the page becomes visible -- no error, no missed lock.
Stable callbacks. Pass onRequest/onRelease/onError once and they run every time the underlying lifecycle event happens, even if the component re-renders.
Force request. forceRequest() is also exposed for cases where you want to skip the visibility check (rare, but useful for kiosk-style apps).

3. OS-Level Notifications

The Manual Way

Web Notifications are simple in principle (new Notification("title")) and tedious in practice. You have to ask for permission first, you have to handle the case where the user has denied permission permanently, you have to feature-detect, and you have to remember to close any notifications your component opens when it unmounts -- otherwise you can leave stale toasts hanging around the OS even after the user has closed the page.

function ManualNotification({ message }: { message: string }) {
  const notifRef = useRef<Notification | null>(null);

  const send = async () => {
    if (!("Notification" in window)) return;
    if (Notification.permission === "denied") return;
    if (Notification.permission !== "granted") {
      const result = await Notification.requestPermission();
      if (result !== "granted") return;
    }
    notifRef.current?.close();
    notifRef.current = new Notification("Reminder", { body: message });
  };

  useEffect(() => {
    return () => notifRef.current?.close();
  }, []);

  return <button onClick={send}>Notify me</button>;
}

This is roughly the minimum viable implementation. It still leaks if the user backgrounds the page mid-flow.

The ReactUse Way: useWebNotification

useWebNotification packages the permission flow, the open/close lifecycle, and SSR-safety into a single hook:

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

function PomodoroTimer() {
  const { isSupported, show, close, ensurePermissions } =
    useWebNotification(true); // request permission on mount

  const onSessionEnd = async () => {
    const granted = await ensurePermissions();
    if (!granted) {
      alert("Pomodoro session complete!"); // graceful fallback
      return;
    }
    show("Time's up!", {
      body: "Take a 5 minute break.",
      icon: "/icons/tomato.png",
      tag: "pomodoro-session",
    });
  };

  return (
    <div>
      <button onClick={onSessionEnd} disabled={!isSupported}>
        End session
      </button>
      <button onClick={close}>Dismiss</button>
    </div>
  );
}

The first argument controls whether the hook should request permission immediately on mount or wait for an explicit ensurePermissions() call. Most apps want the lazy version -- ask for permission only after the user has clicked something -- because otherwise you trigger the browser's permission dialog the instant your component appears, which users find off-putting.

The hook also auto-closes the most recent notification on unmount, so navigating away from the timer cleans up any toasts it produced.

4. Respecting the Notch and Home Bar

The Manual Way

iPhones with a notch and Android phones with a punch hole have safe-area insets. CSS exposes them as env(safe-area-inset-top), etc., but only after you set viewport-fit=cover in the meta tag. Reading the values from JavaScript is fiddly:

function ManualSafeArea() {
  const [insets, setInsets] = useState({
    top: "0px",
    right: "0px",
    bottom: "0px",
    left: "0px",
  });

  useEffect(() => {
    const compute = () => {
      const root = document.documentElement;
      root.style.setProperty("--sa-top", "env(safe-area-inset-top, 0px)");
      root.style.setProperty("--sa-right", "env(safe-area-inset-right, 0px)");
      root.style.setProperty("--sa-bottom", "env(safe-area-inset-bottom, 0px)");
      root.style.setProperty("--sa-left", "env(safe-area-inset-left, 0px)");
      const cs = getComputedStyle(root);
      setInsets({
        top: cs.getPropertyValue("--sa-top"),
        right: cs.getPropertyValue("--sa-right"),
        bottom: cs.getPropertyValue("--sa-bottom"),
        left: cs.getPropertyValue("--sa-left"),
      });
    };
    compute();
    window.addEventListener("resize", compute);
    return () => window.removeEventListener("resize", compute);
  }, []);

  return <div style={{ paddingTop: insets.top, paddingBottom: insets.bottom }} />;
}

That is a lot of plumbing for what is conceptually four numbers.

The ReactUse Way: useScreenSafeArea

useScreenSafeArea returns the four insets directly, debounced and reactive to resize:

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

function SafeAwareLayout({ children }: { children: React.ReactNode }) {
  const [top, right, bottom, left] = useScreenSafeArea();

  return (
    <div
      style={{
        paddingTop: top || 0,
        paddingRight: right || 0,
        paddingBottom: bottom || 0,
        paddingLeft: left || 0,
        minHeight: "100vh",
      }}
    >
      {children}
    </div>
  );
}

Under the hood, the hook installs CSS variables on document.documentElement so the same values are also available to any plain CSS in your stylesheet -- you can use var(--reactuse-safe-area-top) in stylesheets that have nothing to do with React. The JS values let you do conditional padding, and the CSS variables let your design system stay declarative.

5. Title and Favicon as State

The Manual Way

Updating the document title and favicon are imperative side effects in DOM-land but conceptually pure derived state in React-land. The naive approach is one effect per change:

function ManualTitle({ unread }: { unread: number }) {
  useEffect(() => {
    const original = document.title;
    document.title = unread > 0 ? `(${unread}) Inbox` : "Inbox";
    return () => {
      document.title = original;
    };
  }, [unread]);
  return null;
}

function ManualFavicon({ src }: { src: string }) {
  useEffect(() => {
    const link = document.querySelector<HTMLLinkElement>("link[rel*='icon']");
    if (!link) return;
    const previous = link.href;
    link.href = src;
    return () => {
      link.href = previous;
    };
  }, [src]);
  return null;
}

Two effects, two cleanup functions, two opportunities to forget the cleanup and ship a stale title.

The ReactUse Way: useTitle and useFavicon

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

function InboxStatus({ unread }: { unread: number }) {
  useTitle(unread > 0 ? `(${unread}) Inbox` : "Inbox");
  useFavicon(unread > 0 ? "/icons/inbox-unread.svg" : "/icons/inbox.svg");
  return null;
}

That is the whole component. Both hooks treat the title/favicon as derived state, so they update whenever the input changes and clean up automatically. The favicon hook even handles the case where multiple <link rel="icon"> tags exist in the head (modern apps usually have one for image/svg+xml and one for image/png) by updating all of them.

Putting It All Together: Focus-Mode Reading View

Now we combine all six hooks into a focus-mode reading view. The user opens an article, hits "Focus", and the app:

Goes fullscreen
Locks the screen awake so the device does not dim mid-read
Updates the title with how long they have been reading
Changes the favicon to a "do not disturb" indicator
Respects the safe area on the device
Sends a notification after 25 minutes suggesting a break

import { useEffect, useRef, useState } from "react";
import {
  useFullscreen,
  useWakeLock,
  useWebNotification,
  useScreenSafeArea,
  useTitle,
  useFavicon,
} from "@reactuses/core";

const FOCUS_BREAK_MS = 25 * 60 * 1000;

function FocusReader({ article }: { article: { title: string; body: string } }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const [isFocus, setIsFocus] = useState(false);
  const [elapsed, setElapsed] = useState(0);
  const startedAt = useRef<number | null>(null);

  const [isFullscreen, { toggleFullscreen, isEnabled: fsEnabled }] =
    useFullscreen(containerRef, {
      onExit: () => setIsFocus(false),
    });

  const wakeLock = useWakeLock();
  const notif = useWebNotification();
  const [top, right, bottom, left] = useScreenSafeArea();

  const minutes = Math.floor(elapsed / 60000);
  const seconds = Math.floor((elapsed % 60000) / 1000);
  const timer = `${minutes}:${seconds.toString().padStart(2, "0")}`;

  useTitle(isFocus ? `${timer} -- ${article.title}` : article.title);
  useFavicon(isFocus ? "/icons/dnd.svg" : "/icons/book.svg");

  useEffect(() => {
    if (!isFocus) return;
    startedAt.current = Date.now();
    const id = setInterval(() => {
      if (startedAt.current) {
        setElapsed(Date.now() - startedAt.current);
      }
    }, 1000);
    return () => {
      clearInterval(id);
      startedAt.current = null;
      setElapsed(0);
    };
  }, [isFocus]);

  useEffect(() => {
    if (!isFocus || elapsed < FOCUS_BREAK_MS) return;
    let cancelled = false;
    (async () => {
      const granted = await notif.ensurePermissions();
      if (cancelled || !granted) return;
      notif.show("Time for a break", {
        body: "You've been reading for 25 minutes. Stretch, blink, breathe.",
        tag: "focus-break",
      });
    })();
    return () => {
      cancelled = true;
    };
  }, [isFocus, elapsed, notif]);

  const enterFocus = async () => {
    if (!fsEnabled) {
      setIsFocus(true);
      await wakeLock.request();
      return;
    }
    setIsFocus(true);
    toggleFullscreen();
    await wakeLock.request();
  };

  const exitFocus = () => {
    if (isFullscreen) toggleFullscreen();
    wakeLock.release();
    setIsFocus(false);
  };

  return (
    <div
      ref={containerRef}
      style={{
        background: isFocus ? "#0f172a" : "#ffffff",
        color: isFocus ? "#f1f5f9" : "#0f172a",
        minHeight: "100vh",
        paddingTop: top || 24,
        paddingRight: right || 24,
        paddingBottom: bottom || 24,
        paddingLeft: left || 24,
        transition: "background 200ms ease, color 200ms ease",
      }}
    >
      <header
        style={{
          display: "flex",
          justifyContent: "space-between",
          alignItems: "center",
          marginBottom: 24,
        }}
      >
        <h1 style={{ margin: 0, fontSize: 22 }}>{article.title}</h1>
        {isFocus ? (
          <button onClick={exitFocus}>Exit focus ({timer})</button>
        ) : (
          <button onClick={enterFocus}>Focus mode</button>
        )}
      </header>

      <article style={{ maxWidth: 680, margin: "0 auto", lineHeight: 1.7 }}>
        {article.body}
      </article>

      {isFocus && wakeLock.isSupported && (
        <p
          style={{
            position: "fixed",
            bottom: bottom || 12,
            right: right || 12,
            fontSize: 12,
            opacity: 0.6,
            margin: 0,
          }}
        >
          Screen lock: {wakeLock.isActive ? "on" : "off"}
        </p>
      )}
    </div>
  );
}

Six hooks, all doing one thing each:

useFullscreen turns the container into a true fullscreen element on demand
useWakeLock keeps the screen alive while the user is reading
useWebNotification pings them after 25 minutes of focus time
useScreenSafeArea keeps content out from under the notch
useTitle turns the document title into a live timer
useFavicon swaps to a "do not disturb" indicator while focus mode is on

None of the hooks know about each other, but they compose cleanly because each one owns a single browser concern. You can add a seventh capability tomorrow (like network-awareness or device orientation) without touching the existing wiring.

A Note on Permissions

Three of these APIs (notifications, wake lock, fullscreen) require user gestures or explicit permission grants. The hooks expose isSupported flags so you can render fallbacks instead of broken buttons, and they accept callbacks so you can gracefully recover from rejections. The pattern is always the same: feature-detect, ask only when the user has expressed intent, and fall back to a non-API alternative if denied.

Installation

npm i @reactuses/core

Related Hooks

useFullscreen -- Enter, exit, and toggle fullscreen mode on any element
useWakeLock -- Keep the screen awake with auto re-request on visibility change
useWebNotification -- Send OS-level notifications with permission flow handled
useScreenSafeArea -- Read safe area insets reactively
useTitle -- Set the document title declaratively
useFavicon -- Update the favicon based on application state
useDocumentVisibility -- Track whether the document is visible to the user
usePageLeave -- Detect when the cursor leaves the page area
useSupported -- Reactively check whether a browser API is available

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

Build a Full-Stack React App with Vite SSR in 5 Minutes

reactuse.com — Tue, 14 Apr 2026 07:59:00 +0000

Vite is the fastest dev server in the JavaScript ecosystem. But using it for SSR has always meant wiring up renderToPipeableStream, configuring client/server builds, and handling hydration yourself.

Pareto is a React SSR framework built on Vite 7 that handles all of that. You get file-based routing, streaming SSR, loaders, state management, and a 62 KB client bundle — with zero config.

Let's build a full-stack React app in 5 minutes.

1. Create the project (30 seconds)

npx create-pareto@latest my-app
cd my-app
npm install
npm run dev

Open http://localhost:3000. You should see the default page. Edit app/page.tsx and watch it hot-reload instantly via Vite's HMR.

2. Understand the project structure (30 seconds)

my-app/
  app/
    layout.tsx        # Root layout (header, nav, footer)
    page.tsx          # Homepage (/)
    head.tsx          # Root <title> and meta tags
    not-found.tsx     # 404 page
    globals.css       # Global styles
  pareto.config.ts    # Framework config (optional)
  package.json
  tsconfig.json

Every directory inside app/ with a page.tsx becomes a route. Nested directories create nested routes. That's it.

3. Build a page with server data (1 minute)

Create a new route at /posts:

// app/posts/loader.ts
import type { LoaderContext } from '@paretojs/core'

export function loader(ctx: LoaderContext) {
  // This runs on the server only
  return {
    posts: [
      { id: 1, title: 'Hello World', body: 'First post' },
      { id: 2, title: 'Vite SSR', body: 'It is fast' },
    ],
  }
}

// app/posts/page.tsx
import { useLoaderData } from '@paretojs/core'

interface Post {
  id: number
  title: string
  body: string
}

export default function PostsPage() {
  const { posts } = useLoaderData<{ posts: Post[] }>()

  return (
    <div>
      <h1>Posts</h1>
      <ul>
        {posts.map((post) => (
          <li key={post.id}>
            <h2>{post.title}</h2>
            <p>{post.body}</p>
          </li>
        ))}
      </ul>
    </div>
  )
}

// app/posts/head.tsx
export default function Head() {
  return (
    <>
      <title>Posts — My App</title>
      <meta name="description" content="All blog posts" />
    </>
  )
}

Navigate to http://localhost:3000/posts. The loader runs on the server, the HTML is server-rendered, and the page hydrates on the client. View source — the posts are in the HTML.

4. Add streaming for slow data (1 minute)

Real apps fetch from databases and APIs. Some are fast, some are slow. Use defer() to stream slow data without blocking the page:

// app/dashboard/loader.ts
import { defer } from '@paretojs/core'

async function getQuickStats() {
  return { users: 1_234, pageViews: 56_789 }
}

async function getSlowAnalytics() {
  // Simulate a slow API call
  await new Promise((r) => setTimeout(r, 2000))
  return { topPage: '/posts', bounceRate: 0.42 }
}

export async function loader() {
  const stats = await getQuickStats()  // resolve fast data first
  return defer({
    stats,                               // resolved — in initial HTML
    analytics: getSlowAnalytics(),       // Promise — streamed later
  })
}

// app/dashboard/page.tsx
import { useLoaderData, Await } from '@paretojs/core'

export default function DashboardPage() {
  const { stats, analytics } = useLoaderData()

  return (
    <div>
      <h1>Dashboard</h1>
      <p>{stats.users} users · {stats.pageViews} page views</p>

      <Await resolve={analytics} fallback={<p>Loading analytics...</p>}>
        {(data) => (
          <div>
            <p>Top page: {data.topPage}</p>
            <p>Bounce rate: {(data.bounceRate * 100).toFixed(0)}%</p>
          </div>
        )}
      </Await>
    </div>
  )
}

Visit http://localhost:3000/dashboard. The stats appear immediately. The analytics section shows "Loading analytics..." then streams in after 2 seconds. The page never blocks.

5. Add client-side navigation (30 seconds)

Use <Link> for SPA-style navigation without full page reloads:

// app/layout.tsx
import type { PropsWithChildren } from 'react'
import { Link } from '@paretojs/core'

export default function RootLayout({ children }: PropsWithChildren) {
  return (
    <>
      <nav>
        <Link to="/">Home</Link>
        <Link to="/posts">Posts</Link>
        <Link to="/dashboard">Dashboard</Link>
      </nav>
      <main>{children}</main>
    </>
  )
}

Clicks navigate instantly. Loader data is fetched via NDJSON streaming — deferred data streams in progressively, just like the initial SSR render.

6. Add state management (30 seconds)

Pareto ships defineStore() with Immer — no extra dependencies:

// app/stores/theme.ts
import { defineStore } from '@paretojs/core/store'

export const themeStore = defineStore((set) => ({
  mode: 'light' as 'light' | 'dark',
  toggle: () => set((d) => {
    d.mode = d.mode === 'light' ? 'dark' : 'light'
  }),
}))

// Use in any component
import { themeStore } from '../stores/theme'

function ThemeToggle() {
  const { mode, toggle } = themeStore.useStore()
  return <button onClick={toggle}>Theme: {mode}</button>
}

State is automatically serialized during SSR and hydrated on the client. No boilerplate.

7. Add an API endpoint (30 seconds)

Create a route.ts file for JSON API endpoints:

// app/api/time/route.ts
import type { LoaderContext } from '@paretojs/core'

export function loader(ctx: LoaderContext) {
  return { time: new Date().toISOString() }
}

GET http://localhost:3000/api/time returns {"time":"2026-04-03T..."}. Standard REST endpoints, no extra setup.

8. Build and deploy (1 minute)

npm run build
npm run start

That's it. Your production server is a standard Node.js process running Express + Vite's optimized build. Deploy it anywhere you run Node: Docker, Fly.io, Railway, a VPS, Kubernetes.

No special hosting requirements. No serverless runtime compatibility issues. No vendor lock-in.

What you just built

In 5 minutes, you have:

File-based routing — directories map to routes
Server-side rendering — full HTML on first load, great for SEO
Streaming SSR — slow data doesn't block the page
Client navigation — SPA-feel with NDJSON streaming
Head management — per-route <title> and meta tags via React components
State management — Immer-powered stores with automatic SSR hydration
API endpoints — JSON routes alongside your pages
TypeScript — full type safety across loaders and components
62 KB client bundle — 73% smaller than Next.js

All powered by Vite 7 — instant dev server startup, React Fast Refresh, and native ESM in development.

Why Vite for SSR?

	Vite (Pareto)	Webpack (Next.js)	Turbopack (Next.js)
Dev server start	Instant (native ESM)	Seconds (bundling)	Fast (incremental)
HMR	React Fast Refresh	React Fast Refresh	React Fast Refresh
Plugin ecosystem	Vite/Rollup plugins	Webpack loaders	Limited
Config complexity	One `pareto.config.ts`	`next.config.js` + more	`next.config.js` + more
Build output	Optimized Rollup bundle	Webpack bundle	Webpack bundle

Vite's native ESM dev server means zero bundling during development. Your 100-route app starts as fast as your 1-route app.

Next steps

Routing docs — dynamic routes, catch-all routes, nested layouts
Streaming SSR docs — when to use defer(), error handling
State management docs — defineStore, defineContextStore
Benchmarks — Pareto vs Next.js vs React Router performance data

npx create-pareto@latest my-app
cd my-app && npm install && npm run dev

Pareto is a lightweight, streaming-first React SSR framework built on Vite. Documentation

React File Handling: Uploads, Drop Zones, and Object URLs

reactuse.com — Mon, 13 Apr 2026 01:53:48 +0000

React File Handling: Uploads, Drop Zones, and Object URLs

Every non-trivial app eventually needs to handle files. A profile editor needs an avatar uploader. A note-taking app needs to attach images. A CSV importer needs a drop zone. A photo gallery needs thumbnails generated on the client. And every one of these features ends up rebuilt from scratch, because file handling in React touches three different browser APIs (<input type="file">, the Drag and Drop API, and URL.createObjectURL) plus React's own ref and effect machinery -- and most developers wire them together fresh each time.

This post walks through four file-handling primitives that every React app needs eventually: a file picker that opens a dialog without rendering a hidden <input>, a drop zone that accepts dragged files, an object URL helper that previews images without leaks, and a dynamic script loader for third-party libraries you only need on demand. For each one, we will write the manual implementation first so you understand what is happening under the hood, then swap it out for a purpose-built hook from ReactUse. At the end, we will combine all four into a complete photo upload widget that picks, drops, previews, and processes images with an on-demand image library.

1. Picking Files Without a Hidden Input

The Manual Way

The traditional file picker pattern in React looks innocent but hides several footguns:

import { useRef, useState } from "react";

function ManualFilePicker() {
  const inputRef = useRef<HTMLInputElement>(null);
  const [files, setFiles] = useState<FileList | null>(null);

  return (
    <div>
      <input
        ref={inputRef}
        type="file"
        multiple
        accept="image/*"
        style={{ display: "none" }}
        onChange={(e) => setFiles(e.target.files)}
      />
      <button onClick={() => inputRef.current?.click()}>
        Pick images
      </button>
      {files && <p>{files.length} file(s) selected</p>}
    </div>
  );
}

This works, but the moment you try to use it twice the seams show. The hidden <input> lives in your render tree, which means your styling reset has to be aware of it. Resetting the selection requires writing to inputRef.current.value = "" -- a side effect imperative enough that React linters will warn about it. And if you want to await the user's selection (say, inside an async handler that processes the files), you have to invent a one-shot promise yourself.

You also cannot reuse the same component twice on the same page without colliding refs. And if the user picks the same file twice, the change event will not fire the second time -- a famous gotcha that has tripped up generations of React devs.

The ReactUse Way: useFileDialog

useFileDialog lifts the entire input element out of the render tree and gives you a tuple of [files, open, reset]:

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

function ImagePicker() {
  const [files, open, reset] = useFileDialog({
    multiple: true,
    accept: "image/*",
  });

  return (
    <div>
      <button onClick={() => open()}>Pick images</button>
      <button onClick={reset} disabled={!files}>
        Reset
      </button>
      {files && (
        <ul>
          {Array.from(files).map((file) => (
            <li key={file.name}>
              {file.name} -- {(file.size / 1024).toFixed(1)} KB
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}

Three small but important things that the manual version got wrong:

No hidden DOM. The input is created in memory, not in your render tree. Your component output is just the button.
Per-call options. Pass options to open() directly, and they override the hook-level defaults. Want to reuse the same picker for either documents or images? Pass accept at call time.
Real reset. reset() clears both React state and the underlying input element so the same file can be selected again.

The open() function also returns a promise that resolves to the picked files. That makes async flows much cleaner:

const handleUpload = async () => {
  const picked = await open();
  if (!picked) return;
  await uploadAll(Array.from(picked));
};

You no longer have to split your logic across an onChange handler and a button click handler. The picker is just an awaitable function.

2. Drag and Drop File Zones

The Manual Way

Drag and drop is one of those APIs that looks simple in a tutorial and falls apart in production. The naive version:

function ManualDropZone({ onFiles }: { onFiles: (f: File[]) => void }) {
  const [over, setOver] = useState(false);

  return (
    <div
      onDragOver={(e) => {
        e.preventDefault();
        setOver(true);
      }}
      onDragLeave={() => setOver(false)}
      onDrop={(e) => {
        e.preventDefault();
        setOver(false);
        onFiles(Array.from(e.dataTransfer.files));
      }}
      style={{
        border: over ? "2px solid blue" : "2px dashed gray",
        padding: 40,
      }}
    >
      Drop files here
    </div>
  );
}

This seems to work until a user drags over a child element. The browser fires dragleave on the parent the instant the cursor crosses into a child, even though logically the file is still over the zone. Your border flickers. Your over state becomes a lie. To fix it properly, you have to track dragenter and dragleave with a counter, decrement on leave, and only consider the file "gone" when the counter hits zero. You also have to call preventDefault on dragover -- otherwise drop will not fire at all -- and remember that dataTransfer.files is an FileList, not an Array.

Most production drop zones get this wrong. The flicker is the tell.

The ReactUse Way: useDropZone

useDropZone does the counter dance for you:

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

function CsvDropZone() {
  const dropRef = useRef<HTMLDivElement>(null);
  const isOver = useDropZone(dropRef, (files) => {
    if (!files) return;
    const csvs = files.filter((f) => f.name.endsWith(".csv"));
    console.log("Dropped CSVs:", csvs);
  });

  return (
    <div
      ref={dropRef}
      style={{
        border: isOver ? "2px solid #3b82f6" : "2px dashed #cbd5e1",
        background: isOver ? "#eff6ff" : "transparent",
        padding: 60,
        borderRadius: 12,
        textAlign: "center",
        transition: "all 120ms ease",
      }}
    >
      <p style={{ margin: 0 }}>
        {isOver ? "Release to upload" : "Drag CSV files here"}
      </p>
    </div>
  );
}

Notice the API is essentially (target, onDrop) => isOver. That is it. The hook handles dragenter/dragover/dragleave/drop internally, maintains the enter/leave counter so child elements do not break the highlight, prevents the browser's default open-as-new-tab behavior, and gives you back a single boolean to drive your styling.

The callback receives File[] | null -- null when an empty drag happens (yes, that is a thing on some browsers when a user drags non-file content). Your handler can check once and bail out cleanly.

3. Previewing Files with Object URLs

The Manual Way

Once you have a File in hand, you usually want to show it to the user. The browser gives you URL.createObjectURL(blob) to turn any blob into a temporary URL you can stick in an <img> or <video>. The catch: every URL you create allocates memory, and you have to remember to call URL.revokeObjectURL when you are done -- otherwise you leak. In React, "when you are done" usually means "when the component unmounts or the file changes", which is exactly the kind of timing problem effects exist for, and exactly the kind of thing developers forget:

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

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

  if (!url) return null;
  return <img src={url} alt={file?.name} />;
}

This is correct, but it is the kind of correct that is one careless edit away from a leak. The cleanup function and the createObjectURL call have to stay paired forever. Add a conditional return or a forgotten dependency and you have a bug that only shows up in long-lived sessions.

The ReactUse Way: useObjectUrl

useObjectUrl is the single-line version of that effect:

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

function ImagePreview({ file }: { file: File }) {
  const url = useObjectUrl(file);
  if (!url) return null;
  return (
    <img
      src={url}
      alt={file.name}
      style={{ maxWidth: 200, borderRadius: 8 }}
    />
  );
}

The hook owns the lifecycle. When the file prop changes, it revokes the old URL and creates a new one. When the component unmounts, it revokes the last one. There is no way to forget the cleanup because you never write it in the first place.

4. Loading Third-Party Scripts on Demand

The Manual Way

Sometimes the file you want to handle is too big or too rare to ship in your main bundle. Image cropping libraries, PDF parsers, OCR engines, video transcoders -- all of them are dozens of megabytes and worth nothing to a user who never uploads anything. You only want to pay for them after the first file lands.

Loading a script tag manually inside React is a small recipe of its own:

function loadScript(src: string): Promise<void> {
  return new Promise((resolve, reject) => {
    if (document.querySelector(`script[src="${src}"]`)) {
      resolve();
      return;
    }
    const el = document.createElement("script");
    el.src = src;
    el.async = true;
    el.onload = () => resolve();
    el.onerror = () => reject(new Error(`Failed to load ${src}`));
    document.head.appendChild(el);
  });
}

function ManualImageProcessor() {
  const [ready, setReady] = useState(false);

  useEffect(() => {
    loadScript("https://cdn.example.com/heavy-image-lib.js")
      .then(() => setReady(true))
      .catch(console.error);
    // No cleanup -- once loaded, we leave it
  }, []);

  return ready ? <Editor /> : <p>Loading editor...</p>;
}

This handles the happy path but ignores the messy ones: what if the same script is loaded by two components at once (race condition)? What if the script fails halfway and you want to retry? What if you want to actively unload it when the component goes away?

The ReactUse Way: useScriptTag

useScriptTag returns the same primitives you would have written, but with the edge cases handled:

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

function HeavyImageEditor() {
  const [, status, , unload] = useScriptTag(
    "https://cdn.example.com/image-editor.js",
    () => console.log("Editor library ready"),
    { manual: false, async: true },
  );

  if (status === "loading") return <p>Downloading editor...</p>;
  if (status === "error") return <p>Failed to load editor</p>;
  if (status !== "ready") return null;

  return <ImageEditorComponent onClose={unload} />;
}

Four things you get for free:

Singleton behavior. If the same script URL is requested twice, the hook deduplicates -- no race conditions, no double loads.
Status state. idle/loading/ready/error lets you render exactly the right thing at every step.
Manual control. Set manual: true and the script will not load until you call the returned load() function -- perfect for "load on first interaction" patterns.
Unload. Call unload() to remove the script tag from the document. Useful if you want the heavy library out of memory once the user closes the editor.

Putting It All Together: A Photo Upload Widget

Now we combine all four hooks into a single component: a photo upload widget that lets users pick or drop images, previews them on the fly, and lazy-loads a hypothetical client-side resize library only the first time it is needed.

import { useRef, useState } from "react";
import {
  useFileDialog,
  useDropZone,
  useObjectUrl,
  useScriptTag,
} from "@reactuses/core";

interface QueuedImage {
  file: File;
  id: string;
}

function Thumbnail({ image }: { image: QueuedImage }) {
  const url = useObjectUrl(image.file);
  return (
    <figure
      style={{
        margin: 0,
        padding: 8,
        background: "#f8fafc",
        borderRadius: 8,
        textAlign: "center",
      }}
    >
      {url && (
        <img
          src={url}
          alt={image.file.name}
          style={{
            width: 120,
            height: 120,
            objectFit: "cover",
            borderRadius: 4,
          }}
        />
      )}
      <figcaption
        style={{
          marginTop: 6,
          fontSize: 12,
          maxWidth: 120,
          overflow: "hidden",
          textOverflow: "ellipsis",
          whiteSpace: "nowrap",
        }}
      >
        {image.file.name}
      </figcaption>
    </figure>
  );
}

function PhotoUploadWidget() {
  const [queue, setQueue] = useState<QueuedImage[]>([]);
  const [shouldLoadResizer, setShouldLoadResizer] = useState(false);
  const dropRef = useRef<HTMLDivElement>(null);

  const [, openPicker, resetPicker] = useFileDialog({
    multiple: true,
    accept: "image/*",
  });

  const isOver = useDropZone(dropRef, (files) => {
    if (!files) return;
    addFiles(files);
  });

  const [, resizerStatus] = useScriptTag(
    "https://cdn.example.com/image-resize.js",
    () => console.log("Resizer ready"),
    { manual: !shouldLoadResizer },
  );

  const addFiles = (files: File[]) => {
    const newImages = files
      .filter((f) => f.type.startsWith("image/"))
      .map((file) => ({
        file,
        id: `${file.name}-${file.lastModified}-${Math.random()}`,
      }));
    setQueue((prev) => [...prev, ...newImages]);
    if (newImages.length > 0) setShouldLoadResizer(true);
  };

  const handlePick = async () => {
    const picked = await openPicker();
    if (picked) addFiles(Array.from(picked));
  };

  const clearAll = () => {
    setQueue([]);
    resetPicker();
  };

  return (
    <div style={{ maxWidth: 720, fontFamily: "system-ui, sans-serif" }}>
      <div
        ref={dropRef}
        style={{
          border: isOver ? "2px solid #3b82f6" : "2px dashed #cbd5e1",
          background: isOver ? "#eff6ff" : "#ffffff",
          padding: 48,
          borderRadius: 16,
          textAlign: "center",
          transition: "all 120ms ease",
        }}
      >
        <p style={{ marginTop: 0, fontSize: 18 }}>
          {isOver ? "Drop to upload" : "Drag photos here"}
        </p>
        <button
          onClick={handlePick}
          style={{
            padding: "8px 16px",
            borderRadius: 8,
            border: "1px solid #3b82f6",
            background: "#3b82f6",
            color: "white",
            cursor: "pointer",
          }}
        >
          Or pick from device
        </button>
      </div>

      <div
        style={{
          marginTop: 16,
          display: "flex",
          justifyContent: "space-between",
          alignItems: "center",
        }}
      >
        <span style={{ fontSize: 14, color: "#64748b" }}>
          {queue.length} image(s) queued
          {shouldLoadResizer && ` -- resizer: ${resizerStatus}`}
        </span>
        {queue.length > 0 && (
          <button
            onClick={clearAll}
            style={{
              padding: "6px 12px",
              borderRadius: 6,
              border: "1px solid #cbd5e1",
              background: "white",
              cursor: "pointer",
            }}
          >
            Clear all
          </button>
        )}
      </div>

      {queue.length > 0 && (
        <div
          style={{
            marginTop: 16,
            display: "grid",
            gridTemplateColumns: "repeat(auto-fill, minmax(140px, 1fr))",
            gap: 12,
          }}
        >
          {queue.map((image) => (
            <Thumbnail key={image.id} image={image} />
          ))}
        </div>
      )}
    </div>
  );
}

Four hooks, four responsibilities, zero overlap:

useFileDialog owns the click-to-pick flow with an awaitable promise
useDropZone handles drag-and-drop without flicker on child elements
useObjectUrl generates and revokes preview URLs per thumbnail, tied to component lifecycle
useScriptTag lazy-loads the resize library only after the first image arrives, and only once per session

The composition is natural because every hook does one thing. Refs are not shared between them. Effects do not cascade. The component you ship is roughly 100 lines of mostly markup and styling, with the tricky browser plumbing tucked away inside hooks that have been tested and SSR-hardened by the library.

Installation

npm i @reactuses/core

Related Hooks

useFileDialog -- Open a file picker dialog without rendering a hidden input
useDropZone -- Track files being dragged over an element with proper child-aware highlighting
useObjectUrl -- Create and auto-revoke URLs for File and Blob objects
useScriptTag -- Dynamically load external scripts with status tracking and unload support
useEventListener -- Attach event listeners declaratively for custom upload progress events
useSupported -- Check whether the browser supports a given API reactively

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

DEV Community: reactuse.com

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

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

1. usePreferredDark — The Boolean That Starts a Theme System

The Manual Way

The ReactUse Way

2. usePreferredColorScheme — When "Dark" Is Not Enough

3. useColorMode — Theme State With Persistence

4. useReducedMotion — The Cheapest Accessibility Win on the Web

5. usePreferredContrast — Boost the Edges When Asked

6. usePreferredLanguages — Beyond navigator.language

7. useTextDirection — RTL Is Not Just CSS

Putting It All Together: useAppearance

CSS-First Where Possible, JS Where Necessary

Summary

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

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

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

The Manual Way

The ReactUse Way

2. useElementVisibility — The Boolean You Usually Want

3. useResizeObserver — The Right Way to Track Size

The Manual Way

The ReactUse Way

4. useElementSize and useMeasure — Size in Two Flavors

5. useElementBounding — Position Plus Size, Synced

6. useMutationObserver — When the DOM Changes Around You

7. Choosing Between Them

A Worked Example: A Self-Sizing Lazy Card

Performance Notes

Summary

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

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

1. The Tab Title as a Notification Channel

The Manual Way

The ReactUse Way: useTitle

2. State-Aware Favicons

The Manual Way

The ReactUse Way: useFavicon

3. Pause Expensive Work When the Tab is Hidden

The Manual Way

The ReactUse Way: useDocumentVisibility

4. Refresh on Focus

The Manual Way

The ReactUse Way: useWindowsFocus

5. Catch the User Before They Leave

6. Native Notifications — Permission First

Check the State Before You Ask

Ask Only on User Intent

Putting it All Together: An Attention-Aware Chat Tab

Summary

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

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

1. Debounced Async Validation

The Manual Way

The ReactUse Way: useDebounce

2. Controlled or Uncontrolled — Pick One, Support Both

The Manual Way

The ReactUse Way: useControlled

3. Auto-Saving Form Drafts

The Manual Way

The ReactUse Way: useLocalStorage

4. Closing Popovers with Click-Outside

The Manual Way

The ReactUse Way: useClickOutside

Putting It All Together: A Settings Form

Installation

Related Hooks

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

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

1. Live Speech Recognition

The Manual Way

The ReactUse Way: useSpeechRecognition

2. Enumerating Cameras and Microphones

The Manual Way

The ReactUse Way: useMediaDevices

3. Querying Permissions Properly

The Manual Way

The ReactUse Way: usePermission

4. Push-To-Talk With useKeyModifier

6. usePreferredLanguages — Beyond `navigator.language`