Forem: reactuse.com

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 →

Mastering React State Patterns Beyond useState

reactuse.com — Fri, 10 Apr 2026 06:10:11 +0000

Mastering React State Patterns Beyond useState

useState is the workhorse of React state management. It covers simple cases beautifully -- a boolean for a modal, a string for an input, a number for a counter. But the moment your requirements grow even slightly -- you need the previous value, you want to debounce a search term, you are building a component that can be either controlled or uncontrolled -- you find yourself writing the same boilerplate wrappers over and over. Refs to stash old values, setTimeout IDs that must be cleaned up, controlled-vs-uncontrolled negotiation logic that quickly spirals into a mess of useEffect calls.

This post walks through seven state patterns that go beyond basic useState. For each pattern, we start with the manual implementation so you see exactly what is involved, then swap it out for a purpose-built hook from ReactUse. By the end, we will combine all seven hooks into a single interactive settings panel that demonstrates how they compose.

1. Controlled vs Uncontrolled Components with useControlled

The Problem

Reusable UI components often need to work in two modes: controlled (the parent owns the state and passes value + onChange) and uncontrolled (the component manages its own internal state, optionally accepting a defaultValue). Supporting both is the hallmark of well-designed component libraries like MUI and Radix -- but it is surprisingly tedious to implement correctly.

The Manual Way

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

interface CustomInputProps {
  value?: string;
  defaultValue?: string;
  onChange?: (value: string) => void;
}

function CustomInput({ value, defaultValue = "", onChange }: CustomInputProps) {
  const isControlled = value !== undefined;
  const [internalValue, setInternalValue] = useState(defaultValue);

  // Keep a ref to always have the latest controlled value
  const valueRef = useRef(value);
  valueRef.current = value;

  const currentValue = isControlled ? value : internalValue;

  const handleChange = useCallback(
    (e: React.ChangeEvent<HTMLInputElement>) => {
      const next = e.target.value;
      if (!isControlled) {
        setInternalValue(next);
      }
      onChange?.(next);
    },
    [isControlled, onChange]
  );

  return (
    <input
      value={currentValue}
      onChange={handleChange}
      style={{
        padding: "8px 12px",
        border: "1px solid #d1d5db",
        borderRadius: 6,
        fontSize: 16,
      }}
    />
  );
}

This works for a simple input. But the pattern gets more complicated when the controlled value changes externally (you need to sync), when you want to warn developers who switch between controlled and uncontrolled modes, and when the value is a complex object rather than a primitive. Every component that needs this dual-mode behavior repeats this same logic.

With useControlled

useControlled encapsulates the entire controlled/uncontrolled negotiation. It returns a [value, setValue] tuple that works regardless of which mode the consumer uses.

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

interface CustomInputProps {
  value?: string;
  defaultValue?: string;
  onChange?: (value: string) => void;
}

function CustomInput({ value, defaultValue = "", onChange }: CustomInputProps) {
  const [currentValue, setCurrentValue] = useControlled({
    value,
    defaultValue,
    onChange,
  });

  return (
    <input
      value={currentValue}
      onChange={(e) => setCurrentValue(e.target.value)}
      style={{
        padding: "8px 12px",
        border: "1px solid #d1d5db",
        borderRadius: 6,
        fontSize: 16,
      }}
    />
  );
}

// Uncontrolled usage -- component manages its own state
function UncontrolledDemo() {
  return <CustomInput defaultValue="hello" />;
}

// Controlled usage -- parent owns the state
function ControlledDemo() {
  const [text, setText] = useState("");
  return <CustomInput value={text} onChange={setText} />;
}

One hook call replaces the ref, the isControlled check, and the dual-path update logic. The component works identically in both modes, and if a developer accidentally switches between controlled and uncontrolled, the hook handles it gracefully.

2. Tracking Previous Values with usePrevious

The Problem

You frequently need the value from the previous render -- to compare whether a prop changed, to animate transitions between old and new values, or to show "changed from X to Y" UI feedback. React does not provide this out of the box.

The Manual Way

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

function PriceDisplay({ price }: { price: number }) {
  const prevPriceRef = useRef<number | undefined>(undefined);

  useEffect(() => {
    prevPriceRef.current = price;
  });

  const prevPrice = prevPriceRef.current;
  const direction =
    prevPrice === undefined
      ? "neutral"
      : price > prevPrice
        ? "up"
        : price < prevPrice
          ? "down"
          : "neutral";

  return (
    <div style={{ display: "flex", alignItems: "center", gap: 8 }}>
      <span style={{ fontSize: 32, fontWeight: 700 }}>
        ${price.toFixed(2)}
      </span>
      {direction === "up" && (
        <span style={{ color: "#16a34a", fontSize: 20 }}>▲</span>
      )}
      {direction === "down" && (
        <span style={{ color: "#dc2626", fontSize: 20 }}>▼</span>
      )}
      {prevPrice !== undefined && prevPrice !== price && (
        <span style={{ color: "#6b7280", fontSize: 14 }}>
          was ${prevPrice.toFixed(2)}
        </span>
      )}
    </div>
  );
}

The ref-plus-effect trick works, but it is easy to get wrong. If you put the effect before the render logic (or use useLayoutEffect when you should not), the "previous" value may be stale or current. It is also one more piece of boilerplate to copy into every component that needs change detection.

With usePrevious

usePrevious returns the value from the previous render, correctly timed so that during the current render you always see the old value.

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

function PriceDisplay({ price }: { price: number }) {
  const prevPrice = usePrevious(price);

  const direction =
    prevPrice === undefined
      ? "neutral"
      : price > prevPrice
        ? "up"
        : price < prevPrice
          ? "down"
          : "neutral";

  return (
    <div style={{ display: "flex", alignItems: "center", gap: 8 }}>
      <span style={{ fontSize: 32, fontWeight: 700 }}>
        ${price.toFixed(2)}
      </span>
      {direction === "up" && (
        <span style={{ color: "#16a34a", fontSize: 20 }}>▲</span>
      )}
      {direction === "down" && (
        <span style={{ color: "#dc2626", fontSize: 20 }}>▼</span>
      )}
      {prevPrice !== undefined && prevPrice !== price && (
        <span style={{ color: "#6b7280", fontSize: 14 }}>
          was ${prevPrice.toFixed(2)}
        </span>
      )}
    </div>
  );
}

function StockTicker() {
  const [price, setPrice] = useState(142.5);

  return (
    <div style={{ padding: 24 }}>
      <PriceDisplay price={price} />
      <div style={{ marginTop: 16, display: "flex", gap: 8 }}>
        <button onClick={() => setPrice((p) => p + Math.random() * 5)}>
          Price Up
        </button>
        <button onClick={() => setPrice((p) => p - Math.random() * 5)}>
          Price Down
        </button>
      </div>
    </div>
  );
}

No refs, no effects. One line gives you the previous value, correctly synchronized with React's render cycle.

3. Debounced State with useDebounce

The Problem

Search inputs, filter fields, and live-preview editors all suffer from the same issue: updating state on every keystroke triggers expensive operations (API calls, heavy re-renders, complex filtering) far more often than necessary. Debouncing -- waiting until the user stops typing for a specified delay -- is the standard solution.

The Manual Way

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

function ManualDebouncedSearch() {
  const [query, setQuery] = useState("");
  const [debouncedQuery, setDebouncedQuery] = useState("");
  const timerRef = useRef<ReturnType<typeof setTimeout>>();

  useEffect(() => {
    timerRef.current = setTimeout(() => {
      setDebouncedQuery(query);
    }, 300);

    return () => {
      if (timerRef.current) {
        clearTimeout(timerRef.current);
      }
    };
  }, [query]);

  // Clean up on unmount
  useEffect(() => {
    return () => {
      if (timerRef.current) {
        clearTimeout(timerRef.current);
      }
    };
  }, []);

  return (
    <div style={{ padding: 24 }}>
      <input
        value={query}
        onChange={(e) => setQuery(e.target.value)}
        placeholder="Search..."
        style={{
          padding: "8px 12px",
          border: "1px solid #d1d5db",
          borderRadius: 6,
          width: 300,
          fontSize: 16,
        }}
      />
      <p style={{ color: "#6b7280", marginTop: 8 }}>
        Debounced value: <strong>{debouncedQuery}</strong>
      </p>
      <p style={{ color: "#9ca3af", fontSize: 14 }}>
        (This would trigger the API call)
      </p>
    </div>
  );
}

Two state variables, a ref for the timer, an effect to schedule the debounce, another to clean up on unmount. It works, but it is a lot of ceremony for something you will need in dozens of components.

With useDebounce

useDebounce gives you a debounced version of any value. You update the source state normally, and the hook produces a lagging copy that only updates after the specified quiet period.

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

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

  return (
    <div style={{ padding: 24 }}>
      <input
        value={query}
        onChange={(e) => setQuery(e.target.value)}
        placeholder="Search..."
        style={{
          padding: "8px 12px",
          border: "1px solid #d1d5db",
          borderRadius: 6,
          width: 300,
          fontSize: 16,
        }}
      />
      <p style={{ color: "#6b7280", marginTop: 8 }}>
        Debounced value: <strong>{debouncedQuery}</strong>
      </p>
      {query !== debouncedQuery && (
        <p style={{ color: "#f59e0b", fontSize: 14 }}>
          Waiting for you to stop typing...
        </p>
      )}
    </div>
  );
}

One hook, one line. The timer management, cleanup, and synchronization are all handled internally. Compare query !== debouncedQuery to show a "typing" indicator for free.

4. Throttled State with useThrottle

The Problem

Throttling is debouncing's cousin. Instead of waiting for silence, it ensures updates happen at most once per interval -- useful for events that fire continuously, like scroll positions, mouse moves, or real-time data feeds where you want a steady stream of updates rather than a burst at the end.

The Manual Way

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

function ManualThrottledSlider() {
  const [value, setValue] = useState(50);
  const [throttledValue, setThrottledValue] = useState(50);
  const lastRun = useRef(Date.now());
  const timerRef = useRef<ReturnType<typeof setTimeout>>();

  useEffect(() => {
    const now = Date.now();
    const elapsed = now - lastRun.current;
    const delay = 200;

    if (elapsed >= delay) {
      setThrottledValue(value);
      lastRun.current = now;
    } else {
      timerRef.current = setTimeout(() => {
        setThrottledValue(value);
        lastRun.current = Date.now();
      }, delay - elapsed);
    }

    return () => {
      if (timerRef.current) {
        clearTimeout(timerRef.current);
      }
    };
  }, [value]);

  return (
    <div style={{ padding: 24 }}>
      <input
        type="range"
        min={0}
        max={100}
        value={value}
        onChange={(e) => setValue(Number(e.target.value))}
        style={{ width: 300 }}
      />
      <div style={{ marginTop: 12 }}>
        <p>Raw: {value}</p>
        <p>Throttled: {throttledValue}</p>
      </div>
    </div>
  );
}

The throttle logic is tricky to get right. You need to track the last execution time, handle the trailing invocation (so the final value is never lost), and clean up timers. And this is just for a single value -- you would need to repeat all of it for each throttled state.

With useThrottle

useThrottle returns a throttled version of a value, updating at most once per interval while ensuring the final value is always captured.

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

function ThrottledSlider() {
  const [value, setValue] = useState(50);
  const throttledValue = useThrottle(value, 200);

  return (
    <div style={{ padding: 24 }}>
      <input
        type="range"
        min={0}
        max={100}
        value={value}
        onChange={(e) => setValue(Number(e.target.value))}
        style={{ width: 300 }}
      />
      <div style={{ marginTop: 12 }}>
        <p>Raw: {value}</p>
        <p>Throttled: {throttledValue}</p>
      </div>
      <div
        style={{
          marginTop: 16,
          height: 20,
          width: `${throttledValue}%`,
          background: "#4f46e5",
          borderRadius: 4,
          transition: "width 0.1s",
        }}
      />
    </div>
  );
}

The progress bar updates smoothly at 200ms intervals instead of thrashing on every pixel of slider movement. One line of code handles all the timing logic.

5. Cycling Through Options with useCycleList

The Problem

Many UI controls need to cycle through a fixed set of options: theme toggles (light / dark / system), sort orders (ascending / descending / none), view modes (grid / list / compact). The typical approach is a state variable with a function that manually computes the next value.

The Manual Way

import { useState } from "react";

type ViewMode = "grid" | "list" | "compact";
const viewModes: ViewMode[] = ["grid", "list", "compact"];

function ManualViewToggle() {
  const [index, setIndex] = useState(0);
  const mode = viewModes[index];

  const next = () => setIndex((i) => (i + 1) % viewModes.length);
  const prev = () =>
    setIndex((i) => (i - 1 + viewModes.length) % viewModes.length);

  const icons: Record<ViewMode, string> = {
    grid: "▦",
    list: "☰",
    compact: "═",
  };

  return (
    <div style={{ padding: 24 }}>
      <div style={{ display: "flex", alignItems: "center", gap: 12 }}>
        <button onClick={prev} style={{ fontSize: 20, cursor: "pointer" }}>
          ←
        </button>
        <div
          style={{
            padding: "8px 16px",
            background: "#f1f5f9",
            borderRadius: 8,
            fontSize: 18,
            minWidth: 120,
            textAlign: "center",
          }}
        >
          {icons[mode]} {mode}
        </div>
        <button onClick={next} style={{ fontSize: 20, cursor: "pointer" }}>
          →
        </button>
      </div>
    </div>
  );
}

Simple enough for one toggle, but the modular arithmetic for wrapping and the separate index tracking are boilerplate that shows up wherever you need cycling behavior. It also does not support jumping to a specific value or reacting to list changes.

With useCycleList

useCycleList manages cycling through an array of values, providing next, prev, and direct go functions along with the current value and index.

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

type ViewMode = "grid" | "list" | "compact";

function ViewToggle() {
  const [mode, { next, prev }] = useCycleList<ViewMode>(
    ["grid", "list", "compact"]
  );

  const icons: Record<ViewMode, string> = {
    grid: "▦",
    list: "☰",
    compact: "═",
  };

  return (
    <div style={{ padding: 24 }}>
      <div style={{ display: "flex", alignItems: "center", gap: 12 }}>
        <button onClick={prev} style={{ fontSize: 20, cursor: "pointer" }}>
          ←
        </button>
        <div
          style={{
            padding: "8px 16px",
            background: "#f1f5f9",
            borderRadius: 8,
            fontSize: 18,
            minWidth: 120,
            textAlign: "center",
          }}
        >
          {icons[mode]} {mode}
        </div>
        <button onClick={next} style={{ fontSize: 20, cursor: "pointer" }}>
          →
        </button>
      </div>
    </div>
  );
}

No index management, no modular arithmetic. The hook gives you the current value and navigation functions. It is especially handy for theme toggles where clicking cycles through light, dark, and system modes.

6. Numeric State with useCounter

The Problem

Counters appear everywhere -- quantity selectors in e-commerce, pagination controls, step indicators, zoom levels. Each one needs increment, decrement, reset, and often min/max clamping. Writing this from scratch every time is tedious.

The Manual Way

import { useCallback, useState } from "react";

function ManualQuantityPicker() {
  const [count, setCount] = useState(1);
  const min = 1;
  const max = 99;

  const increment = useCallback(
    () => setCount((c) => Math.min(c + 1, max)),
    [max]
  );
  const decrement = useCallback(
    () => setCount((c) => Math.max(c - 1, min)),
    [min]
  );
  const reset = useCallback(() => setCount(1), []);

  return (
    <div style={{ padding: 24 }}>
      <div style={{ display: "flex", alignItems: "center", gap: 12 }}>
        <button
          onClick={decrement}
          disabled={count <= min}
          style={{
            width: 36,
            height: 36,
            borderRadius: "50%",
            border: "1px solid #d1d5db",
            background: count <= min ? "#f3f4f6" : "#fff",
            fontSize: 18,
            cursor: count <= min ? "not-allowed" : "pointer",
          }}
        >
          -
        </button>
        <span style={{ fontSize: 24, fontWeight: 600, minWidth: 40, textAlign: "center" }}>
          {count}
        </span>
        <button
          onClick={increment}
          disabled={count >= max}
          style={{
            width: 36,
            height: 36,
            borderRadius: "50%",
            border: "1px solid #d1d5db",
            background: count >= max ? "#f3f4f6" : "#fff",
            fontSize: 18,
            cursor: count >= max ? "not-allowed" : "pointer",
          }}
        >
          +
        </button>
        <button onClick={reset} style={{ marginLeft: 12, fontSize: 14, color: "#6b7280" }}>
          Reset
        </button>
      </div>
    </div>
  );
}

The clamping logic, the disabled states, the memoized callbacks -- all standard boilerplate that repeats for every counter in your app.

With useCounter

useCounter provides count, inc, dec, set, and reset out of the box, with optional min/max bounds.

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

function QuantityPicker() {
  const [count, { inc, dec, reset }] = useCounter(1, {
    min: 1,
    max: 99,
  });

  return (
    <div style={{ padding: 24 }}>
      <div style={{ display: "flex", alignItems: "center", gap: 12 }}>
        <button
          onClick={() => dec()}
          disabled={count <= 1}
          style={{
            width: 36,
            height: 36,
            borderRadius: "50%",
            border: "1px solid #d1d5db",
            background: count <= 1 ? "#f3f4f6" : "#fff",
            fontSize: 18,
            cursor: count <= 1 ? "not-allowed" : "pointer",
          }}
        >
          -
        </button>
        <span style={{ fontSize: 24, fontWeight: 600, minWidth: 40, textAlign: "center" }}>
          {count}
        </span>
        <button
          onClick={() => inc()}
          disabled={count >= 99}
          style={{
            width: 36,
            height: 36,
            borderRadius: "50%",
            border: "1px solid #d1d5db",
            background: count >= 99 ? "#f3f4f6" : "#fff",
            fontSize: 18,
            cursor: count >= 99 ? "not-allowed" : "pointer",
          }}
        >
          +
        </button>
        <button onClick={reset} style={{ marginLeft: 12, fontSize: 14, color: "#6b7280" }}>
          Reset
        </button>
      </div>
    </div>
  );
}

The hook handles clamping internally. You pass min and max once and never worry about boundary violations in your increment/decrement logic.

7. Class-Style setState with useSetState

The Problem

React class components had a convenient setState that accepted partial objects and merged them into the existing state. With hooks, useState replaces the entire value. If your state is an object with multiple fields, every update needs a spread: setState(prev => ({ ...prev, name: 'new' })). For complex forms or settings objects with many fields, this gets verbose and error-prone (forgetting the spread silently drops fields).

The Manual Way

import { useCallback, useState } from "react";

interface FormState {
  name: string;
  email: string;
  role: string;
  notifications: boolean;
}

function ManualSettingsForm() {
  const [state, setFullState] = useState<FormState>({
    name: "",
    email: "",
    role: "viewer",
    notifications: true,
  });

  // Every update must spread the previous state
  const setState = useCallback(
    (patch: Partial<FormState>) =>
      setFullState((prev) => ({ ...prev, ...patch })),
    []
  );

  return (
    <form style={{ padding: 24, display: "flex", flexDirection: "column", gap: 12, maxWidth: 400 }}>
      <input
        value={state.name}
        onChange={(e) => setState({ name: e.target.value })}
        placeholder="Name"
        style={{ padding: "8px 12px", border: "1px solid #d1d5db", borderRadius: 6 }}
      />
      <input
        value={state.email}
        onChange={(e) => setState({ email: e.target.value })}
        placeholder="Email"
        style={{ padding: "8px 12px", border: "1px solid #d1d5db", borderRadius: 6 }}
      />
      <select
        value={state.role}
        onChange={(e) => setState({ role: e.target.value })}
        style={{ padding: "8px 12px", border: "1px solid #d1d5db", borderRadius: 6 }}
      >
        <option value="viewer">Viewer</option>
        <option value="editor">Editor</option>
        <option value="admin">Admin</option>
      </select>
      <label style={{ display: "flex", alignItems: "center", gap: 8 }}>
        <input
          type="checkbox"
          checked={state.notifications}
          onChange={(e) => setState({ notifications: e.target.checked })}
        />
        Email notifications
      </label>
      <pre style={{ background: "#f8fafc", padding: 12, borderRadius: 6, fontSize: 13 }}>
        {JSON.stringify(state, null, 2)}
      </pre>
    </form>
  );
}

You have to create the merging setState wrapper yourself. If another developer on your team forgets the wrapper and calls setFullState directly with a partial object, fields silently disappear.

With useSetState

useSetState works like the class component setState -- pass a partial object and it merges into the existing state automatically.

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

interface FormState {
  name: string;
  email: string;
  role: string;
  notifications: boolean;
}

function SettingsForm() {
  const [state, setState] = useSetState<FormState>({
    name: "",
    email: "",
    role: "viewer",
    notifications: true,
  });

  return (
    <form style={{ padding: 24, display: "flex", flexDirection: "column", gap: 12, maxWidth: 400 }}>
      <input
        value={state.name}
        onChange={(e) => setState({ name: e.target.value })}
        placeholder="Name"
        style={{ padding: "8px 12px", border: "1px solid #d1d5db", borderRadius: 6 }}
      />
      <input
        value={state.email}
        onChange={(e) => setState({ email: e.target.value })}
        placeholder="Email"
        style={{ padding: "8px 12px", border: "1px solid #d1d5db", borderRadius: 6 }}
      />
      <select
        value={state.role}
        onChange={(e) => setState({ role: e.target.value })}
        style={{ padding: "8px 12px", border: "1px solid #d1d5db", borderRadius: 6 }}
      >
        <option value="viewer">Viewer</option>
        <option value="editor">Editor</option>
        <option value="admin">Admin</option>
      </select>
      <label style={{ display: "flex", alignItems: "center", gap: 8 }}>
        <input
          type="checkbox"
          checked={state.notifications}
          onChange={(e) => setState({ notifications: e.target.checked })}
        />
        Email notifications
      </label>
      <pre style={{ background: "#f8fafc", padding: 12, borderRadius: 6, fontSize: 13 }}>
        {JSON.stringify(state, null, 2)}
      </pre>
    </form>
  );
}

The setState returned by the hook accepts partial objects and merges them. No wrapper function needed, no risk of accidentally replacing the entire state.

Putting It All Together: A Settings Panel

These hooks compose naturally. Here is a settings panel that uses all seven:

import {
  useControlled,
  usePrevious,
  useDebounce,
  useThrottle,
  useCycleList,
  useCounter,
  useSetState,
} from "@reactuses/core";
import { useState } from "react";

// A controlled/uncontrolled search input
function SearchInput({
  value,
  defaultValue,
  onChange,
}: {
  value?: string;
  defaultValue?: string;
  onChange?: (v: string) => void;
}) {
  const [currentValue, setCurrentValue] = useControlled({
    value,
    defaultValue: defaultValue ?? "",
    onChange,
  });

  return (
    <input
      value={currentValue}
      onChange={(e) => setCurrentValue(e.target.value)}
      placeholder="Search settings..."
      style={{
        padding: "8px 12px",
        border: "1px solid #d1d5db",
        borderRadius: 6,
        width: "100%",
        fontSize: 14,
      }}
    />
  );
}

function SettingsPanel() {
  // Search with debounce
  const [searchQuery, setSearchQuery] = useState("");
  const debouncedSearch = useDebounce(searchQuery, 300);
  const prevSearch = usePrevious(debouncedSearch);

  // Theme cycling
  const [theme, { next: nextTheme }] = useCycleList([
    "light",
    "dark",
    "system",
  ]);

  // Font size with counter
  const [fontSize, { inc: fontUp, dec: fontDown, reset: fontReset }] =
    useCounter(16, { min: 12, max: 24 });

  // Throttled live preview
  const throttledFontSize = useThrottle(fontSize, 150);

  // Form state with merge
  const [settings, setSettings] = useSetState({
    username: "",
    email: "",
    notifications: true,
    language: "en",
  });

  const themeColors: Record<string, { bg: string; text: string }> = {
    light: { bg: "#ffffff", text: "#1e293b" },
    dark: { bg: "#1e293b", text: "#f8fafc" },
    system: { bg: "#f1f5f9", text: "#334155" },
  };

  const allSettings = [
    "username",
    "email",
    "notifications",
    "language",
    "theme",
    "font size",
  ];

  const filtered = debouncedSearch
    ? allSettings.filter((s) =>
        s.toLowerCase().includes(debouncedSearch.toLowerCase())
      )
    : allSettings;

  return (
    <div
      style={{
        padding: 24,
        maxWidth: 500,
        margin: "0 auto",
        background: themeColors[theme].bg,
        color: themeColors[theme].text,
        borderRadius: 12,
        transition: "all 0.3s",
      }}
    >
      <h2 style={{ marginTop: 0 }}>Settings</h2>

      {/* Controlled search input */}
      <SearchInput value={searchQuery} onChange={setSearchQuery} />

      {prevSearch && prevSearch !== debouncedSearch && (
        <p style={{ fontSize: 12, opacity: 0.6, margin: "4px 0" }}>
          Changed from "{prevSearch}" to "{debouncedSearch}"
        </p>
      )}

      <p style={{ fontSize: 12, opacity: 0.6 }}>
        Showing {filtered.length} of {allSettings.length} settings
      </p>

      {/* Theme toggle */}
      {filtered.includes("theme") && (
        <div
          style={{
            display: "flex",
            justifyContent: "space-between",
            alignItems: "center",
            padding: "12px 0",
            borderBottom: "1px solid rgba(128,128,128,0.2)",
          }}
        >
          <span>Theme</span>
          <button
            onClick={nextTheme}
            style={{
              padding: "6px 16px",
              borderRadius: 6,
              border: "1px solid rgba(128,128,128,0.3)",
              background: "transparent",
              color: "inherit",
              cursor: "pointer",
            }}
          >
            {theme}
          </button>
        </div>
      )}

      {/* Font size counter */}
      {filtered.includes("font size") && (
        <div
          style={{
            display: "flex",
            justifyContent: "space-between",
            alignItems: "center",
            padding: "12px 0",
            borderBottom: "1px solid rgba(128,128,128,0.2)",
          }}
        >
          <span>Font size</span>
          <div style={{ display: "flex", alignItems: "center", gap: 8 }}>
            <button onClick={() => fontDown()}>-</button>
            <span style={{ fontWeight: 600 }}>{fontSize}px</span>
            <button onClick={() => fontUp()}>+</button>
            <button
              onClick={fontReset}
              style={{ fontSize: 12, color: "inherit", opacity: 0.6 }}
            >
              reset
            </button>
          </div>
        </div>
      )}

      {/* Live preview with throttled font size */}
      <p
        style={{
          fontSize: throttledFontSize,
          padding: "12px 0",
          transition: "font-size 0.15s",
          borderBottom: "1px solid rgba(128,128,128,0.2)",
        }}
      >
        Preview text at {throttledFontSize}px
      </p>

      {/* Merged state form fields */}
      {filtered.includes("username") && (
        <div style={{ padding: "12px 0" }}>
          <label style={{ display: "block", fontSize: 13, marginBottom: 4 }}>
            Username
          </label>
          <input
            value={settings.username}
            onChange={(e) => setSettings({ username: e.target.value })}
            style={{
              padding: "6px 10px",
              border: "1px solid rgba(128,128,128,0.3)",
              borderRadius: 4,
              width: "100%",
              background: "transparent",
              color: "inherit",
            }}
          />
        </div>
      )}

      {filtered.includes("notifications") && (
        <label
          style={{
            display: "flex",
            alignItems: "center",
            gap: 8,
            padding: "12px 0",
          }}
        >
          <input
            type="checkbox"
            checked={settings.notifications}
            onChange={(e) =>
              setSettings({ notifications: e.target.checked })
            }
          />
          Enable notifications
        </label>
      )}
    </div>
  );
}

Seven hooks, zero conflicts. useControlled powers the search input so it can also be used uncontrolled elsewhere. useDebounce prevents the filter from running on every keystroke. usePrevious shows what the search was before. useCycleList handles the theme toggle. useCounter manages the font size with bounds. useThrottle smooths the live preview updates. useSetState keeps the form fields in a single merged-state object. Each hook handles one concern, and they compose without any special glue code.

Installation

npm i @reactuses/core

Related Hooks

useControlled -- Build components that work both controlled and uncontrolled
usePrevious -- Access the value from the previous render
useDebounce -- Debounce any value by a specified delay
useThrottle -- Throttle any value to update at most once per interval
useCycleList -- Cycle through an array of values with next/prev
useCounter -- Numeric state with inc/dec/reset and optional min/max
useSetState -- Merge partial objects into state like class-component setState
useBoolean -- Boolean state with toggle, setTrue, setFalse
useToggle -- Toggle between two values
useLocalStorage -- Persist state to localStorage with automatic serialization

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

React Streaming SSR Without Server Components — A Practical Guide

reactuse.com — Thu, 09 Apr 2026 02:35:39 +0000

React Server Components get all the attention for streaming SSR. But RSC isn't the only way — and for many apps, it's more complexity than you need.

You can stream HTML from the server using renderToPipeableStream, defer(), and standard Suspense — no server components, no "use client" directives, no mental gymnastics about which component runs where. This post shows how, using Pareto as the framework.

What streaming SSR actually means

Traditional SSR works like this:

Request comes in
Server fetches all data
Server renders complete HTML
Browser receives the full page

The problem: if any data source is slow, the entire page is slow. A 200ms database query + a 2s external API call = every user waits 2+ seconds for first paint.

Streaming SSR works differently:

Request comes in
Server sends the HTML shell + fast data immediately
Slow data streams in as it resolves
Browser progressively renders each section

Users see content in milliseconds. Slow data appears as it becomes available. No full-page loading spinners.

The building blocks

You need three things:

A loader that separates fast and slow data — defer() marks which values should stream
Suspense boundaries in your component — <Await> wraps each streaming section
A streaming SSR runtime — renderToPipeableStream under the hood

Pareto wires all three together. Here's a complete example.

Building a streaming dashboard

Imagine a dashboard that shows:

User count (fast — cached, ~5ms)
Activity feed (medium — database query, ~100ms)
Analytics chart (slow — external API, ~800ms)

The loader

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

export async function loader(ctx: LoaderContext) {
  // Fast: resolve before passing to defer
  const userCount = await getCachedUserCount()

  return defer({
    userCount,  // already resolved — in initial HTML

    // Medium: streams in ~100ms after initial HTML
    activityFeed: db.query('SELECT * FROM activity ORDER BY created_at DESC LIMIT 20'),

    // Slow: streams in ~800ms after initial HTML
    analytics: fetch('https://analytics-api.example.com/dashboard')
      .then(res => res.json()),
  })
}

defer() takes an object. Synchronously resolved values (like userCount) are included in the initial HTML. Promises (like activityFeed and analytics) stream in as they resolve.

The page component

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

export default function Dashboard() {
  const { userCount, activityFeed, analytics } = useLoaderData()

  return (
    <div className="dashboard">
      {/* Renders immediately — data is already resolved */}
      <header>
        <h1>Dashboard</h1>
        <span className="stat">{userCount} active users</span>
      </header>

      {/* Streams in after ~100ms */}
      <section>
        <h2>Recent Activity</h2>
        <Await resolve={activityFeed} fallback={<ActivitySkeleton />}>
          {(feed) => (
            <ul>
              {feed.map(item => (
                <li key={item.id}>{item.user} {item.action}</li>
              ))}
            </ul>
          )}
        </Await>
      </section>

      {/* Streams in after ~800ms */}
      <section>
        <h2>Analytics</h2>
        <Await resolve={analytics} fallback={<ChartSkeleton />}>
          {(data) => <AnalyticsChart data={data} />}
        </Await>
      </section>
    </div>
  )
}

What the user sees

0ms: HTML shell + header with user count
~100ms: Activity feed appears, replacing skeleton
~800ms: Analytics chart appears, replacing skeleton

Compare this to traditional SSR: the user would see nothing until ~800ms (waiting for the slowest data source), then everything at once.

Error handling in streams

What happens when a deferred promise rejects? The <Await> component throws, and the nearest error boundary catches it.

import { ParetoErrorBoundary } from '@paretojs/core'

<ParetoErrorBoundary fallback={({ error }) => (
  <div className="error-card">
    <p>Failed to load analytics: {error.message}</p>
    <button onClick={() => window.location.reload()}>Retry</button>
  </div>
)}>
  <Await resolve={analytics} fallback={<ChartSkeleton />}>
    {(data) => <AnalyticsChart data={data} />}
  </Await>
</ParetoErrorBoundary>

The key: wrap each <Await> in its own error boundary. If the analytics API fails, the rest of the page (header, activity feed) stays intact. Without a boundary, one failed stream takes down the entire page.

When NOT to stream

Streaming isn't always the right choice:

Don't stream SEO-critical content. Search crawlers may not execute JavaScript to reveal streamed sections. If content must be in the initial HTML for SEO, return it synchronously from the loader.

Don't stream small payloads. If all your data resolves in <50ms, the streaming setup overhead isn't worth it. Just return everything synchronously.

Don't stream dependent data. If your component can't render anything meaningful without all data present, deferring individual pieces just creates multiple loading spinners instead of one. Await all promises in the loader instead:

// Better: one loading state instead of three spinners
export function loader() {
  const [users, posts, comments] = await Promise.all([
    getUsers(), getPosts(), getComments()
  ])
  return { users, posts, comments }
}

Client-side navigation: NDJSON streaming

On the initial page load, streaming SSR delivers HTML progressively. But what about client-side navigations?

In Pareto 4.0, client navigations use NDJSON (newline-delimited JSON) streaming. When you click a <Link>, the client fetches loader data as a stream — non-deferred data arrives first, deferred data streams in as it resolves.

This means Suspense boundaries work identically on first load and on navigation. No behavioral difference, no special handling. The same <Await> component that shows a skeleton during SSR shows the same skeleton during client navigation.

Performance under load

Streaming SSR isn't just a UX improvement — it changes how your server handles concurrent requests.

Traditional SSR holds the response open until all data is ready. Under 100 concurrent connections, if each request waits for a 200ms API call, the server queues up fast.

Streaming SSR sends the initial HTML immediately and releases the rendering thread. The slow data streams asynchronously. This is why Pareto sustains 2,022 streaming req/s vs Next.js at 310 req/s under load — a 6.5x difference.

In practice: a streaming SSR dashboard serving 2,000 req/s needs 1 Pareto server vs 7 Next.js instances.

The complete pattern

// loader.ts — separate fast and slow data
import { defer } from '@paretojs/core'

export async function loader() {
  const fast = await getSyncData()   // resolve first
  return defer({
    fast,                            // resolved — in initial HTML
    slow: fetchExternalAPI(),        // Promise — streamed
  })
}

// page.tsx — standard React + Await
import { useLoaderData, Await } from '@paretojs/core'

export default function Page() {
  const { fast, slow } = useLoaderData()
  return (
    <div>
      <div>{fast.value}</div>
      <Await resolve={slow} fallback={<Skeleton />}>
        {(data) => <SlowSection data={data} />}
      </Await>
    </div>
  )
}

// head.tsx — meta tags with loader data
export default function Head({ loaderData }) {
  return <title>{loaderData.fast.title}</title>
}

No server components. No "use client". No framework magic. Just loaders, React, and Suspense.

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 Mouse Tracking and Interactive Effects Without External Libraries

reactuse.com — Wed, 08 Apr 2026 06:39:37 +0000

React Mouse Tracking and Interactive Effects

The mouse is the primary input device on desktop, and building delightful interactions around it -- custom cursors that follow the pointer, buttons that react to presses, scratch-to-reveal cards, color pickers that sample any pixel on screen -- is what separates a polished app from a plain one. Yet every one of these effects requires a different browser API, a different set of event listeners, and a different cleanup strategy. Most developers either reach for a large interaction library or write fragile imperative code that leaks listeners and forgets about touch devices.

This post takes a hands-on approach. We will build five mouse-driven interactions, starting each time with the manual implementation so you understand the plumbing, then replacing it with a purpose-built hook from ReactUse. By the end you will have a toolkit of composable hooks that cover mouse tracking, press detection, element bounding, scratch surfaces, and color picking -- all SSR-safe and ready for production.

1. Tracking Mouse Position with useMouse

The Manual Way

Tracking the cursor seems simple -- listen to mousemove and read clientX/clientY. But real-world use cases need more: page-relative coordinates, element-relative coordinates, and throttling to avoid layout thrashing.

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

interface MousePos {
  clientX: number;
  clientY: number;
  pageX: number;
  pageY: number;
  elementX: number;
  elementY: number;
}

function ManualMouseTracker() {
  const boxRef = useRef<HTMLDivElement>(null);
  const [pos, setPos] = useState<MousePos>({
    clientX: 0,
    clientY: 0,
    pageX: 0,
    pageY: 0,
    elementX: 0,
    elementY: 0,
  });

  useEffect(() => {
    const onMove = (e: MouseEvent) => {
      const box = boxRef.current;
      let elX = 0;
      let elY = 0;
      if (box) {
        const rect = box.getBoundingClientRect();
        elX = e.pageX - (rect.left + window.scrollX);
        elY = e.pageY - (rect.top + window.scrollY);
      }
      setPos({
        clientX: e.clientX,
        clientY: e.clientY,
        pageX: e.pageX,
        pageY: e.pageY,
        elementX: elX,
        elementY: elY,
      });
    };

    document.addEventListener("mousemove", onMove);
    return () => document.removeEventListener("mousemove", onMove);
  }, []);

  return (
    <div style={{ padding: 24 }}>
      <p>
        Page: ({pos.pageX}, {pos.pageY})
      </p>
      <div
        ref={boxRef}
        style={{
          width: 300,
          height: 200,
          background: "#f1f5f9",
          borderRadius: 8,
          position: "relative",
          overflow: "hidden",
        }}
      >
        <div
          style={{
            width: 12,
            height: 12,
            borderRadius: "50%",
            background: "#4f46e5",
            position: "absolute",
            left: pos.elementX - 6,
            top: pos.elementY - 6,
            pointerEvents: "none",
          }}
        />
        <p style={{ padding: 16, margin: 0 }}>
          Element: ({Math.round(pos.elementX)}, {Math.round(pos.elementY)})
        </p>
      </div>
    </div>
  );
}

This works for a basic demo, but it fires on every pixel of movement without throttling, it does not use requestAnimationFrame to batch updates, and it does not report screen-relative or element-dimension values. Adding all that means more state, more refs, and more cleanup.

With useMouse

useMouse returns a comprehensive state object with screenX, screenY, clientX, clientY, pageX, pageY, plus element-relative elementX, elementY, elementW, elementH, elementPosX, and elementPosY. Updates are batched through requestAnimationFrame automatically.

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

function MouseTracker() {
  const boxRef = useRef<HTMLDivElement>(null);
  const mouse = useMouse(boxRef);

  return (
    <div style={{ padding: 24 }}>
      <p>
        Page: ({mouse.pageX}, {mouse.pageY})
      </p>
      <p>
        Client: ({mouse.clientX}, {mouse.clientY})
      </p>
      <div
        ref={boxRef}
        style={{
          width: 300,
          height: 200,
          background: "#f1f5f9",
          borderRadius: 8,
          position: "relative",
          overflow: "hidden",
        }}
      >
        {/* Cursor dot that follows the mouse within the element */}
        <div
          style={{
            width: 12,
            height: 12,
            borderRadius: "50%",
            background: "#4f46e5",
            position: "absolute",
            left: mouse.elementX - 6,
            top: mouse.elementY - 6,
            pointerEvents: "none",
            transition: "opacity 0.15s",
            opacity: Number.isNaN(mouse.elementX) ? 0 : 1,
          }}
        />
        <p style={{ padding: 16, margin: 0 }}>
          Element: ({Math.round(mouse.elementX)},{" "}
          {Math.round(mouse.elementY)})
        </p>
        <p style={{ padding: "0 16px", margin: 0 }}>
          Element size: {mouse.elementW} x {mouse.elementH}
        </p>
      </div>
    </div>
  );
}

One hook call gives you every coordinate system you might need. The requestAnimationFrame batching is built in, so you never see torn frames. Passing a ref makes the hook compute element-relative values automatically; omit the ref and you still get all the global coordinates.

Practical example: spotlight hover effect

A common design pattern is a card that "lights up" around the cursor on hover. With useMouse, this becomes trivial:

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

function SpotlightCard() {
  const cardRef = useRef<HTMLDivElement>(null);
  const { elementX, elementY, elementW, elementH } = useMouse(cardRef);

  const isInside =
    !Number.isNaN(elementX) &&
    elementX >= 0 &&
    elementX <= elementW &&
    elementY >= 0 &&
    elementY <= elementH;

  return (
    <div
      ref={cardRef}
      style={{
        width: 360,
        height: 240,
        borderRadius: 12,
        border: "1px solid #e2e8f0",
        position: "relative",
        overflow: "hidden",
        background: "#0f172a",
        color: "#f8fafc",
        padding: 24,
      }}
    >
      {/* Radial spotlight */}
      <div
        style={{
          position: "absolute",
          inset: 0,
          background: isInside
            ? `radial-gradient(circle 180px at ${elementX}px ${elementY}px, rgba(99,102,241,0.25), transparent)`
            : "transparent",
          pointerEvents: "none",
          transition: "opacity 0.2s",
        }}
      />
      <h3 style={{ position: "relative" }}>Premium Plan</h3>
      <p style={{ position: "relative", opacity: 0.7 }}>
        Hover anywhere on this card to see the spotlight follow your cursor.
      </p>
    </div>
  );
}

2. Detecting Mouse Press State with useMousePressed

The Manual Way

Detecting whether the mouse button is currently held down requires listening to mousedown and mouseup at minimum. If you also want touch support, you need touchstart, touchend, and touchcancel. And if drag events are involved, add dragstart, drop, and dragend:

import { useEffect, useState } from "react";

function ManualPressDetector() {
  const [pressed, setPressed] = useState(false);
  const [source, setSource] = useState<string | null>(null);

  useEffect(() => {
    const onMouseDown = () => {
      setPressed(true);
      setSource("mouse");
    };
    const onTouchStart = () => {
      setPressed(true);
      setSource("touch");
    };
    const onUp = () => {
      setPressed(false);
      setSource(null);
    };

    window.addEventListener("mousedown", onMouseDown);
    window.addEventListener("mouseup", onUp);
    window.addEventListener("touchstart", onTouchStart);
    window.addEventListener("touchend", onUp);
    window.addEventListener("touchcancel", onUp);

    return () => {
      window.removeEventListener("mousedown", onMouseDown);
      window.removeEventListener("mouseup", onUp);
      window.removeEventListener("touchstart", onTouchStart);
      window.removeEventListener("touchend", onUp);
      window.removeEventListener("touchcancel", onUp);
    };
  }, []);

  return (
    <div
      style={{
        padding: 40,
        background: pressed ? "#4f46e5" : "#f1f5f9",
        color: pressed ? "#fff" : "#0f172a",
        transition: "all 0.15s",
        borderRadius: 12,
        textAlign: "center",
        userSelect: "none",
      }}
    >
      {pressed ? `Pressed! (${source})` : "Click or touch and hold anywhere"}
    </div>
  );
}

Five event listeners, five cleanup calls, and this still does not handle drag events or scoped targets. If you want the press detection to apply only within a specific element, you need to restructure the entire approach.

With useMousePressed

useMousePressed wraps all of this into a single call. It returns a [pressed, sourceType] tuple, supports mouse, touch, and drag events out of the box, and can be scoped to a specific element via a ref.

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

function PressDetector() {
  const areaRef = useRef<HTMLDivElement>(null);
  const [pressed, sourceType] = useMousePressed(areaRef);

  return (
    <div
      ref={areaRef}
      style={{
        padding: 40,
        background: pressed ? "#4f46e5" : "#f1f5f9",
        color: pressed ? "#fff" : "#0f172a",
        transition: "all 0.15s",
        borderRadius: 12,
        textAlign: "center",
        userSelect: "none",
        cursor: "pointer",
      }}
    >
      {pressed
        ? `Pressed via ${sourceType}!`
        : "Click or touch and hold this area"}
    </div>
  );
}

The touch and drag options default to true, so touch and drag presses are detected automatically. Set either to false if you want to limit detection to mouse clicks only.

Practical example: hold-to-confirm button

Hold-to-confirm buttons prevent accidental actions. Here is one built with useMousePressed:

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

function HoldToConfirm({ onConfirm }: { onConfirm: () => void }) {
  const btnRef = useRef<HTMLButtonElement>(null);
  const [pressed] = useMousePressed(btnRef);
  const [progress, setProgress] = useState(0);

  useEffect(() => {
    if (!pressed) {
      setProgress(0);
      return;
    }

    const interval = setInterval(() => {
      setProgress((prev) => {
        const next = prev + 2;
        if (next >= 100) {
          clearInterval(interval);
          onConfirm();
          return 100;
        }
        return next;
      });
    }, 30);

    return () => clearInterval(interval);
  }, [pressed, onConfirm]);

  return (
    <button
      ref={btnRef}
      style={{
        position: "relative",
        padding: "12px 32px",
        border: "none",
        borderRadius: 8,
        background: "#ef4444",
        color: "#fff",
        fontSize: 16,
        cursor: "pointer",
        overflow: "hidden",
      }}
    >
      <div
        style={{
          position: "absolute",
          inset: 0,
          background: "rgba(0,0,0,0.2)",
          width: `${progress}%`,
          transition: pressed ? "none" : "width 0.3s",
        }}
      />
      <span style={{ position: "relative" }}>
        {progress >= 100
          ? "Confirmed!"
          : pressed
            ? `Hold... ${progress}%`
            : "Hold to Delete"}
      </span>
    </button>
  );
}

3. Element Position Tracking with useElementBounding

The Manual Way

Knowing the exact position and size of an element on the page is essential for tooltips, popovers, drag-and-drop hit zones, and more. The manual approach uses getBoundingClientRect plus listeners for scroll and resize:

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

interface BoundingRect {
  x: number;
  y: number;
  width: number;
  height: number;
  top: number;
  right: number;
  bottom: number;
  left: number;
}

function ManualBounding() {
  const boxRef = useRef<HTMLDivElement>(null);
  const [rect, setRect] = useState<BoundingRect>({
    x: 0, y: 0, width: 0, height: 0,
    top: 0, right: 0, bottom: 0, left: 0,
  });

  useEffect(() => {
    const el = boxRef.current;
    if (!el) return;

    const update = () => {
      const r = el.getBoundingClientRect();
      setRect({
        x: r.x, y: r.y, width: r.width, height: r.height,
        top: r.top, right: r.right, bottom: r.bottom, left: r.left,
      });
    };

    update();
    window.addEventListener("scroll", update, { passive: true });
    window.addEventListener("resize", update, { passive: true });

    // ResizeObserver for element-level resizing
    const ro = new ResizeObserver(update);
    ro.observe(el);

    return () => {
      window.removeEventListener("scroll", update);
      window.removeEventListener("resize", update);
      ro.disconnect();
    };
  }, []);

  return (
    <div style={{ padding: 24, minHeight: "200vh" }}>
      <div
        ref={boxRef}
        style={{
          width: 200,
          height: 120,
          background: "#4f46e5",
          borderRadius: 8,
          marginTop: 100,
        }}
      />
      <pre style={{ marginTop: 16 }}>
        {JSON.stringify(rect, null, 2)}
      </pre>
    </div>
  );
}

Three separate event sources (scroll, resize, ResizeObserver), three cleanup paths, and this still does not handle cases like CSS transforms or layout shifts caused by sibling elements.

With useElementBounding

useElementBounding returns a live bounding rectangle that automatically updates on scroll, resize, and element dimension changes via ResizeObserver. It returns { x, y, width, height, top, right, bottom, left, update }.

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

function BoundingTracker() {
  const boxRef = useRef<HTMLDivElement>(null);
  const { x, y, width, height, top, right, bottom, left } =
    useElementBounding(boxRef);

  return (
    <div style={{ padding: 24, minHeight: "200vh" }}>
      <div
        ref={boxRef}
        style={{
          width: 200,
          height: 120,
          background: "#4f46e5",
          borderRadius: 8,
          marginTop: 100,
          color: "#fff",
          display: "flex",
          alignItems: "center",
          justifyContent: "center",
        }}
      >
        {Math.round(width)} x {Math.round(height)}
      </div>
      <div
        style={{
          marginTop: 16,
          padding: 16,
          background: "#f8fafc",
          borderRadius: 8,
          fontFamily: "monospace",
          fontSize: 14,
        }}
      >
        <div>x: {Math.round(x)}, y: {Math.round(y)}</div>
        <div>top: {Math.round(top)}, right: {Math.round(right)}</div>
        <div>bottom: {Math.round(bottom)}, left: {Math.round(left)}</div>
      </div>
    </div>
  );
}

All the wiring -- scroll listener, resize listener, ResizeObserver -- is handled internally. You can also pass options like windowScroll: false or windowResize: false to disable specific update triggers if they are not needed for your use case.

Practical example: dynamic tooltip positioning

Tooltips need to know where their trigger element is at all times. Here is a tooltip that stays pinned to an element as the page scrolls:

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

function TooltipDemo() {
  const btnRef = useRef<HTMLButtonElement>(null);
  const { x, y, width, height } = useElementBounding(btnRef);
  const [show, setShow] = useState(false);

  return (
    <div style={{ padding: 24, minHeight: "200vh" }}>
      <div style={{ marginTop: 300 }}>
        <button
          ref={btnRef}
          onMouseEnter={() => setShow(true)}
          onMouseLeave={() => setShow(false)}
          style={{
            padding: "8px 16px",
            background: "#4f46e5",
            color: "#fff",
            border: "none",
            borderRadius: 6,
            cursor: "pointer",
          }}
        >
          Hover me (scroll to test)
        </button>
      </div>

      {show && (
        <div
          style={{
            position: "fixed",
            left: x + width / 2,
            top: y - 8,
            transform: "translate(-50%, -100%)",
            padding: "6px 12px",
            background: "#1e293b",
            color: "#fff",
            borderRadius: 6,
            fontSize: 13,
            whiteSpace: "nowrap",
            pointerEvents: "none",
            zIndex: 1000,
          }}
        >
          I follow the button even on scroll!
          <div
            style={{
              position: "absolute",
              bottom: -4,
              left: "50%",
              transform: "translateX(-50%) rotate(45deg)",
              width: 8,
              height: 8,
              background: "#1e293b",
            }}
          />
        </div>
      )}
    </div>
  );
}

Because useElementBounding updates on scroll, the tooltip position stays correct even as the user scrolls the page -- without any extra event listeners on your part.

4. Building a Scratch Pad with useScratch

The Manual Way

A scratch interaction -- where the user drags across a surface and you track the starting point, current position, and deltas -- requires handling both mouse and touch events, computing element-relative coordinates, and tracking timing:

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

interface ScratchState {
  isScratching: boolean;
  startX: number;
  startY: number;
  x: number;
  y: number;
  dx: number;
  dy: number;
}

function ManualScratchPad() {
  const canvasRef = useRef<HTMLDivElement>(null);
  const [state, setState] = useState<ScratchState>({
    isScratching: false,
    startX: 0,
    startY: 0,
    x: 0,
    y: 0,
    dx: 0,
    dy: 0,
  });
  const [lines, setLines] = useState<Array<{ x: number; y: number }>>([]);
  const scratchingRef = useRef(false);

  useEffect(() => {
    const el = canvasRef.current;
    if (!el) return;

    const getRelativePos = (clientX: number, clientY: number) => {
      const rect = el.getBoundingClientRect();
      return {
        x: clientX - rect.left,
        y: clientY - rect.top,
      };
    };

    const onMouseDown = (e: MouseEvent) => {
      e.preventDefault();
      const pos = getRelativePos(e.clientX, e.clientY);
      scratchingRef.current = true;
      setState({
        isScratching: true,
        startX: pos.x,
        startY: pos.y,
        x: pos.x,
        y: pos.y,
        dx: 0,
        dy: 0,
      });
      setLines([pos]);
    };

    const onMouseMove = (e: MouseEvent) => {
      if (!scratchingRef.current) return;
      const pos = getRelativePos(e.clientX, e.clientY);
      setState((prev) => ({
        ...prev,
        dx: pos.x - prev.x,
        dy: pos.y - prev.y,
        x: pos.x,
        y: pos.y,
      }));
      setLines((prev) => [...prev, pos]);
    };

    const onMouseUp = () => {
      scratchingRef.current = false;
      setState((prev) => ({ ...prev, isScratching: false }));
    };

    el.addEventListener("mousedown", onMouseDown);
    window.addEventListener("mousemove", onMouseMove);
    window.addEventListener("mouseup", onMouseUp);

    return () => {
      el.removeEventListener("mousedown", onMouseDown);
      window.removeEventListener("mousemove", onMouseMove);
      window.removeEventListener("mouseup", onMouseUp);
    };
  }, []);

  return (
    <div style={{ padding: 24 }}>
      <div
        ref={canvasRef}
        style={{
          width: 400,
          height: 300,
          background: "#f1f5f9",
          borderRadius: 8,
          cursor: "crosshair",
          position: "relative",
          overflow: "hidden",
        }}
      >
        <svg
          style={{ position: "absolute", inset: 0 }}
          width={400}
          height={300}
        >
          {lines.length > 1 && (
            <polyline
              points={lines.map((p) => `${p.x},${p.y}`).join(" ")}
              fill="none"
              stroke="#4f46e5"
              strokeWidth={3}
              strokeLinecap="round"
              strokeLinejoin="round"
            />
          )}
        </svg>
        <p style={{ padding: 16, margin: 0, color: "#94a3b8" }}>
          {state.isScratching ? "Drawing..." : "Draw here"}
        </p>
      </div>
    </div>
  );
}

This is already quite verbose, and it only handles mouse events -- no touch support. Adding touch means duplicating every handler for touchstart, touchmove, and touchend. It also does not use requestAnimationFrame, so rapid movements can overwhelm React's rendering.

With useScratch

useScratch handles both mouse and touch events, computes element-relative coordinates, tracks timing, and batches state updates via requestAnimationFrame. It returns a state object with isScratching, x, y, dx, dy, elW, elH, and timestamps.

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

function ScratchPad() {
  const padRef = useRef<HTMLDivElement>(null);
  const state = useScratch(padRef);
  const [points, setPoints] = useState<Array<{ x: number; y: number }>>([]);

  useEffect(() => {
    if (state.isScratching && state.x !== undefined && state.y !== undefined) {
      setPoints((prev) => [...prev, { x: state.x!, y: state.y! }]);
    }
    if (!state.isScratching) {
      // Optionally clear on release
    }
  }, [state.isScratching, state.x, state.y]);

  return (
    <div style={{ padding: 24 }}>
      <div
        ref={padRef}
        style={{
          width: 400,
          height: 300,
          background: "#f1f5f9",
          borderRadius: 8,
          cursor: "crosshair",
          position: "relative",
          overflow: "hidden",
          touchAction: "none",
        }}
      >
        <svg
          style={{ position: "absolute", inset: 0 }}
          width={400}
          height={300}
        >
          {points.length > 1 && (
            <polyline
              points={points.map((p) => `${p.x},${p.y}`).join(" ")}
              fill="none"
              stroke="#4f46e5"
              strokeWidth={3}
              strokeLinecap="round"
              strokeLinejoin="round"
            />
          )}
        </svg>
        <div style={{ padding: 16, color: "#94a3b8", position: "relative" }}>
          {state.isScratching ? (
            <span>
              Drawing at ({Math.round(state.x ?? 0)},{" "}
              {Math.round(state.y ?? 0)}) -- delta: (
              {Math.round(state.dx ?? 0)}, {Math.round(state.dy ?? 0)})
            </span>
          ) : (
            "Draw here (mouse or touch)"
          )}
        </div>
      </div>
      <button
        onClick={() => setPoints([])}
        style={{
          marginTop: 12,
          padding: "8px 16px",
          background: "#e2e8f0",
          border: "none",
          borderRadius: 6,
          cursor: "pointer",
        }}
      >
        Clear
      </button>
    </div>
  );
}

Touch support, requestAnimationFrame batching, and element-relative coordinate computation are all handled by the hook. You also get callbacks via the onScratchStart, onScratch, and onScratchEnd options if you prefer event-driven patterns over reactive state.

Practical example: scratch-to-reveal card

A classic scratch-to-reveal effect where the user scratches off a covering layer:

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

function ScratchToReveal() {
  const coverRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const [revealed, setRevealed] = useState(false);

  const state = useScratch(coverRef, {
    onScratch: (s) => {
      const canvas = canvasRef.current;
      if (!canvas || !s.x || !s.y) return;
      const ctx = canvas.getContext("2d");
      if (!ctx) return;

      ctx.globalCompositeOperation = "destination-out";
      ctx.beginPath();
      ctx.arc(s.x, s.y, 20, 0, Math.PI * 2);
      ctx.fill();

      // Check how much has been scratched
      const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
      const pixels = imageData.data;
      let transparent = 0;
      for (let i = 3; i < pixels.length; i += 4) {
        if (pixels[i] === 0) transparent++;
      }
      const ratio = transparent / (pixels.length / 4);
      if (ratio > 0.5) {
        setRevealed(true);
      }
    },
  });

  const initCanvas = useCallback((el: HTMLCanvasElement | null) => {
    if (!el) return;
    (canvasRef as React.MutableRefObject<HTMLCanvasElement>).current = el;
    const ctx = el.getContext("2d");
    if (ctx) {
      ctx.fillStyle = "#94a3b8";
      ctx.fillRect(0, 0, el.width, el.height);
      ctx.font = "16px sans-serif";
      ctx.fillStyle = "#fff";
      ctx.textAlign = "center";
      ctx.fillText("Scratch here!", el.width / 2, el.height / 2);
    }
  }, []);

  return (
    <div
      ref={coverRef}
      style={{
        width: 300,
        height: 150,
        position: "relative",
        borderRadius: 12,
        overflow: "hidden",
        cursor: "crosshair",
        touchAction: "none",
      }}
    >
      {/* Hidden content */}
      <div
        style={{
          position: "absolute",
          inset: 0,
          background: "linear-gradient(135deg, #4f46e5, #7c3aed)",
          display: "flex",
          alignItems: "center",
          justifyContent: "center",
          color: "#fff",
          fontSize: 20,
          fontWeight: 700,
        }}
      >
        You won a prize!
      </div>

      {/* Scratch layer */}
      {!revealed && (
        <canvas
          ref={initCanvas}
          width={300}
          height={150}
          style={{ position: "absolute", inset: 0 }}
        />
      )}
    </div>
  );
}

5. Picking Colors from the Screen with useEyeDropper

The Manual Way

The EyeDropper API is relatively new and only available in Chromium-based browsers. Using it directly means checking for support, handling the async nature of the picker, and dealing with the abort signal:

import { useState, useCallback } from "react";

function ManualColorPicker() {
  const [color, setColor] = useState<string | null>(null);
  const [error, setError] = useState<string | null>(null);

  const isSupported =
    typeof window !== "undefined" && "EyeDropper" in window;

  const pickColor = useCallback(async () => {
    if (!isSupported) {
      setError("EyeDropper API is not supported in this browser");
      return;
    }
    try {
      const dropper = new (window as any).EyeDropper();
      const result = await dropper.open();
      setColor(result.sRGBHex);
      setError(null);
    } catch (e: any) {
      if (e.name !== "AbortError") {
        setError(e.message);
      }
    }
  }, [isSupported]);

  return (
    <div style={{ padding: 24 }}>
      <button
        onClick={pickColor}
        disabled={!isSupported}
        style={{
          padding: "8px 16px",
          background: "#4f46e5",
          color: "#fff",
          border: "none",
          borderRadius: 6,
          cursor: isSupported ? "pointer" : "not-allowed",
          opacity: isSupported ? 1 : 0.5,
        }}
      >
        Pick a Color
      </button>
      {color && (
        <div style={{ marginTop: 16, display: "flex", alignItems: "center", gap: 12 }}>
          <div
            style={{
              width: 48,
              height: 48,
              borderRadius: 8,
              background: color,
              border: "1px solid #e2e8f0",
            }}
          />
          <code>{color}</code>
        </div>
      )}
      {error && <p style={{ color: "#ef4444" }}>{error}</p>}
    </div>
  );
}

The boilerplate around feature detection, async handling, and error management is not terrible, but it adds up when you use it in multiple places.

With useEyeDropper

useEyeDropper abstracts the EyeDropper API into a simple [isSupported, open] tuple. The open function returns a promise that resolves to { sRGBHex: string }. If the API is not supported, isSupported is false and open resolves with an empty string.

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

function ColorPicker() {
  const [isSupported, open] = useEyeDropper();
  const [color, setColor] = useState<string | null>(null);

  const pickColor = async () => {
    const { sRGBHex } = await open();
    if (sRGBHex) {
      setColor(sRGBHex);
    }
  };

  return (
    <div style={{ padding: 24 }}>
      {!isSupported && (
        <p style={{ color: "#f59e0b" }}>
          EyeDropper API is not supported in your browser.
        </p>
      )}
      <button
        onClick={pickColor}
        disabled={!isSupported}
        style={{
          padding: "8px 16px",
          background: "#4f46e5",
          color: "#fff",
          border: "none",
          borderRadius: 6,
          cursor: isSupported ? "pointer" : "not-allowed",
          opacity: isSupported ? 1 : 0.5,
        }}
      >
        Pick Color from Screen
      </button>
      {color && (
        <div
          style={{
            marginTop: 16,
            display: "flex",
            alignItems: "center",
            gap: 12,
          }}
        >
          <div
            style={{
              width: 48,
              height: 48,
              borderRadius: 8,
              background: color,
              border: "1px solid #e2e8f0",
            }}
          />
          <code style={{ fontSize: 18 }}>{color}</code>
        </div>
      )}
    </div>
  );
}

Clean, declarative, and the support check is always available so you can show a fallback UI in unsupported browsers.

Practical example: color palette builder

Build a palette by picking colors from anywhere on screen:

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

function PaletteBuilder() {
  const [isSupported, open] = useEyeDropper();
  const [palette, setPalette] = useState<string[]>([]);

  const addColor = async () => {
    const { sRGBHex } = await open();
    if (sRGBHex) {
      setPalette((prev) =>
        prev.includes(sRGBHex) ? prev : [...prev, sRGBHex]
      );
    }
  };

  const removeColor = (hex: string) => {
    setPalette((prev) => prev.filter((c) => c !== hex));
  };

  return (
    <div style={{ padding: 24 }}>
      <h3>Color Palette Builder</h3>
      <button
        onClick={addColor}
        disabled={!isSupported}
        style={{
          padding: "8px 20px",
          background: "#4f46e5",
          color: "#fff",
          border: "none",
          borderRadius: 6,
          cursor: "pointer",
          marginBottom: 16,
        }}
      >
        + Pick Color
      </button>

      <div style={{ display: "flex", gap: 8, flexWrap: "wrap" }}>
        {palette.map((hex) => (
          <div
            key={hex}
            onClick={() => removeColor(hex)}
            title="Click to remove"
            style={{
              width: 64,
              height: 64,
              borderRadius: 8,
              background: hex,
              border: "2px solid #e2e8f0",
              cursor: "pointer",
              display: "flex",
              alignItems: "flex-end",
              justifyContent: "center",
              paddingBottom: 4,
            }}
          >
            <span
              style={{
                fontSize: 10,
                background: "rgba(255,255,255,0.8)",
                borderRadius: 3,
                padding: "1px 4px",
              }}
            >
              {hex}
            </span>
          </div>
        ))}
      </div>
      {palette.length === 0 && (
        <p style={{ color: "#94a3b8" }}>
          Pick colors from anywhere on your screen to build a palette.
        </p>
      )}
    </div>
  );
}

6. Putting It All Together: An Interactive Canvas Tool

These hooks compose naturally. Here is an interactive drawing tool that combines mouse tracking, press detection, element bounding, scratch interaction, and a color picker:

import {
  useMouse,
  useMousePressed,
  useElementBounding,
  useScratch,
  useEyeDropper,
} from "@reactuses/core";
import { useRef, useState, useEffect } from "react";

function InteractiveCanvasTool() {
  const canvasRef = useRef<HTMLDivElement>(null);
  const toolbarRef = useRef<HTMLDivElement>(null);

  // Track mouse for the cursor preview
  const mouse = useMouse(canvasRef);

  // Detect press state for visual feedback
  const [pressed] = useMousePressed(canvasRef);

  // Track canvas position for absolute positioning of overlays
  const canvasBounds = useElementBounding(canvasRef);

  // Scratch state for drawing
  const scratch = useScratch(canvasRef);

  // Color picker
  const [isEyeDropperSupported, openEyeDropper] = useEyeDropper();

  // Drawing state
  const [brushColor, setBrushColor] = useState("#4f46e5");
  const [brushSize, setBrushSize] = useState(4);
  const [strokes, setStrokes] = useState<
    Array<{ points: Array<{ x: number; y: number }>; color: string; size: number }>
  >([]);
  const [currentStroke, setCurrentStroke] = useState<
    Array<{ x: number; y: number }>
  >([]);

  // Accumulate points during a scratch
  useEffect(() => {
    if (scratch.isScratching && scratch.x !== undefined && scratch.y !== undefined) {
      setCurrentStroke((prev) => [...prev, { x: scratch.x!, y: scratch.y! }]);
    }
  }, [scratch.isScratching, scratch.x, scratch.y]);

  // Save stroke when scratching ends
  useEffect(() => {
    if (!scratch.isScratching && currentStroke.length > 1) {
      setStrokes((prev) => [
        ...prev,
        { points: currentStroke, color: brushColor, size: brushSize },
      ]);
      setCurrentStroke([]);
    }
  }, [scratch.isScratching, currentStroke, brushColor, brushSize]);

  const pickColor = async () => {
    const { sRGBHex } = await openEyeDropper();
    if (sRGBHex) {
      setBrushColor(sRGBHex);
    }
  };

  const clearCanvas = () => {
    setStrokes([]);
    setCurrentStroke([]);
  };

  const isInsideCanvas =
    !Number.isNaN(mouse.elementX) &&
    mouse.elementX >= 0 &&
    mouse.elementX <= (canvasBounds.width || 0) &&
    mouse.elementY >= 0 &&
    mouse.elementY <= (canvasBounds.height || 0);

  return (
    <div style={{ padding: 24, maxWidth: 700 }}>
      <h2>Interactive Canvas Tool</h2>

      {/* Toolbar */}
      <div
        ref={toolbarRef}
        style={{
          display: "flex",
          alignItems: "center",
          gap: 16,
          marginBottom: 16,
          padding: "12px 16px",
          background: "#f8fafc",
          borderRadius: 8,
          flexWrap: "wrap",
        }}
      >
        <label style={{ display: "flex", alignItems: "center", gap: 8 }}>
          Color:
          <input
            type="color"
            value={brushColor}
            onChange={(e) => setBrushColor(e.target.value)}
            style={{
              width: 32,
              height: 32,
              border: "none",
              borderRadius: 4,
              cursor: "pointer",
            }}
          />
        </label>

        {isEyeDropperSupported && (
          <button
            onClick={pickColor}
            style={{
              padding: "6px 12px",
              background: "#e2e8f0",
              border: "none",
              borderRadius: 6,
              cursor: "pointer",
              fontSize: 13,
            }}
          >
            Pick from Screen
          </button>
        )}

        <label style={{ display: "flex", alignItems: "center", gap: 8 }}>
          Size:
          <input
            type="range"
            min={1}
            max={20}
            value={brushSize}
            onChange={(e) => setBrushSize(Number(e.target.value))}
            style={{ width: 100 }}
          />
          <span style={{ fontSize: 13 }}>{brushSize}px</span>
        </label>

        <button
          onClick={clearCanvas}
          style={{
            padding: "6px 12px",
            background: "#fee2e2",
            color: "#ef4444",
            border: "none",
            borderRadius: 6,
            cursor: "pointer",
            fontSize: 13,
          }}
        >
          Clear
        </button>
      </div>

      {/* Canvas */}
      <div
        ref={canvasRef}
        style={{
          width: "100%",
          height: 400,
          background: "#fff",
          border: "2px solid #e2e8f0",
          borderRadius: 8,
          position: "relative",
          overflow: "hidden",
          cursor: "crosshair",
          touchAction: "none",
        }}
      >
        {/* SVG drawing surface */}
        <svg
          style={{ position: "absolute", inset: 0 }}
          width="100%"
          height="100%"
        >
          {/* Completed strokes */}
          {strokes.map((stroke, i) => (
            <polyline
              key={i}
              points={stroke.points.map((p) => `${p.x},${p.y}`).join(" ")}
              fill="none"
              stroke={stroke.color}
              strokeWidth={stroke.size}
              strokeLinecap="round"
              strokeLinejoin="round"
            />
          ))}

          {/* Current stroke being drawn */}
          {currentStroke.length > 1 && (
            <polyline
              points={currentStroke.map((p) => `${p.x},${p.y}`).join(" ")}
              fill="none"
              stroke={brushColor}
              strokeWidth={brushSize}
              strokeLinecap="round"
              strokeLinejoin="round"
            />
          )}
        </svg>

        {/* Cursor preview */}
        {isInsideCanvas && !pressed && (
          <div
            style={{
              position: "absolute",
              left: mouse.elementX - brushSize / 2,
              top: mouse.elementY - brushSize / 2,
              width: brushSize,
              height: brushSize,
              borderRadius: "50%",
              border: `1px solid ${brushColor}`,
              pointerEvents: "none",
            }}
          />
        )}
      </div>

      {/* Status bar */}
      <div
        style={{
          marginTop: 12,
          padding: "8px 16px",
          background: "#f8fafc",
          borderRadius: 6,
          fontSize: 13,
          display: "flex",
          gap: 24,
          color: "#64748b",
        }}
      >
        <span>
          Cursor: ({Math.round(mouse.elementX)},{" "}
          {Math.round(mouse.elementY)})
        </span>
        <span>
          Canvas: {Math.round(canvasBounds.width)} x{" "}
          {Math.round(canvasBounds.height)}
        </span>
        <span>
          State: {scratch.isScratching ? "Drawing" : pressed ? "Pressed" : "Idle"}
        </span>
        <span>Strokes: {strokes.length}</span>
      </div>
    </div>
  );
}

Five hooks, each handling one responsibility:

useMouse provides the cursor position for the brush preview circle
useMousePressed drives visual feedback and the status indicator
useElementBounding keeps track of the canvas dimensions for boundary checks
useScratch handles the actual drawing interaction with both mouse and touch
useEyeDropper lets the user sample colors from anywhere on screen

They share refs naturally, do not conflict, and all clean up on unmount.

Installation

npm i @reactuses/core

Related Hooks

useMouse -- Track mouse position across multiple coordinate systems
useMousePressed -- Detect mouse/touch/drag press state
useElementBounding -- Get live bounding rectangle of an element
useScratch -- Track scratch/drag gestures on an element
useEyeDropper -- Pick colors from anywhere on screen
useEventListener -- Attach event listeners declaratively
useRafState -- State updates batched with requestAnimationFrame
useElementSize -- Track element dimensions reactively
useSupported -- Check browser API support reactively

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

From Next.js to Pareto: What Changes and What Stays the Same

reactuse.com — Fri, 03 Apr 2026 01:51:49 +0000

You know Next.js. You know file-based routing, layouts, loaders, SSR. You probably also know the pain: server components vs client components, the "use client" dance, mysterious hydration errors, and a 233 KB client bundle before you write a single line of app code.

Pareto gives you the same SSR patterns — but without the complexity. Standard React components, Vite instead of Webpack/Turbopack, and a 62 KB client bundle. This post walks through exactly what changes when you move from Next.js to Pareto, and what stays familiar.

The mental model shift

Next.js (App Router): Every component is a server component by default. Want useState? Add "use client". Data fetching happens via async server components or route-level generateMetadata. You're constantly thinking about the server/client boundary.

Pareto: Every component is a regular React component that runs on both server and client. Data fetching happens in loader.ts files — a pattern borrowed from Remix. There's no "use client" directive because there's no server component / client component split.

Next.js mental model:  "Is this a server component or a client component?"
Pareto mental model:   "Is this data or UI?"

Routing: almost identical

If you know Next.js App Router conventions, Pareto's routing is immediately familiar:

Next.js	Pareto	Purpose
`page.tsx`	`page.tsx`	Route component
`layout.tsx`	`layout.tsx`	Wrapping layout
—	`loader.ts`	Server-side data
`loading.tsx`	Suspense + `<Await>`	Loading states
`error.tsx`	`ParetoErrorBoundary`	Error handling
`not-found.tsx`	`not-found.tsx`	404 page
`route.ts`	`route.ts`	API endpoint
`head.tsx` / `generateMetadata`	`head.tsx`	Meta tags

The biggest difference: Pareto uses a dedicated loader.ts file for data fetching instead of making the page component async.

Data fetching: loaders replace async components

Next.js (App Router):

// app/dashboard/page.tsx (server component)
export default async function Dashboard() {
  const stats = await db.getStats()
  return <h1>{stats.total} users</h1>
}

Pareto:

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

export function loader(ctx: LoaderContext) {
  return { stats: db.getStats() }
}

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

export default function Dashboard() {
  const { stats } = useLoaderData<{ stats: { total: number } }>()
  return <h1>{stats.total} users</h1>
}

Two files instead of one, but the separation is intentional: data fetching is explicit, testable, and never mixed with rendering logic. The component is standard React — no async, no await, no server-only constraints.

Streaming: `defer()` instead of Suspense gymnastics

Next.js: Streaming requires splitting your page into server and client components, coordinating loading.tsx boundaries, and understanding which components block the initial render.

Pareto: Call defer() in your loader. Wrap slow data in <Await>. Done.

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

export async function loader() {
  const userCount = await getUserCount()  // resolve fast data first

  return defer({
    userCount,                             // resolved — sent immediately
    activityFeed: getActivityFeed(),       // slow — streamed later
    analytics: getAnalytics(),             // slower — streamed even later
  })
}

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

export default function Dashboard() {
  const { userCount, activityFeed, analytics } = useLoaderData()

  return (
    <div>
      <h1>{userCount} users</h1>

      <Await resolve={activityFeed} fallback={<Skeleton />}>
        {(feed) => <ActivityList items={feed} />}
      </Await>

      <Await resolve={analytics} fallback={<ChartSkeleton />}>
        {(data) => <AnalyticsChart data={data} />}
      </Await>
    </div>
  )
}

Each <Await> creates its own Suspense boundary. Fast data renders immediately. Slow data streams in progressively. Same behavior on initial SSR load and client-side navigation (via NDJSON streaming in Pareto 4.0).

Head management: React components, not config objects

Next.js:

export async function generateMetadata({ params }) {
  const post = await getPost(params.id)
  return { title: post.title, description: post.excerpt }
}

Pareto:

// app/blog/[id]/head.tsx
export default function Head({ loaderData }: { loaderData: { post: Post } }) {
  return (
    <>
      <title>{loaderData.post.title}</title>
      <meta name="description" content={loaderData.post.excerpt} />
      <meta property="og:title" content={loaderData.post.title} />
    </>
  )
}

It's a React component. You can use conditional logic, compose from shared components, or render anything valid in <head>. Head components merge from root layout to page — the deepest route wins for duplicate tags.

State management: built-in, not bolted on

Next.js has no opinion on state management. You bring your own Redux, Zustand, Jotai, etc., and figure out SSR hydration yourself.

Pareto ships defineStore() with Immer:

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

const { useStore, getState, setState } = defineStore((set) => ({
  items: [] as CartItem[],
  total: 0,
  addItem: (item: CartItem) => set((d) => {
    d.items.push(item)
    d.total += item.price
  }),
}))

SSR hydration is automatic. State defined on the server is serialized and restored on the client without any manual dehydrate / rehydrate boilerplate.

Configuration: one file

Next.js: next.config.js for framework config + separate Webpack/Turbopack customization + potential middleware.ts + environment variable conventions.

Pareto: One pareto.config.ts:

import type { ParetoConfig } from '@paretojs/core'

const config: ParetoConfig = {
  configureVite(config) {
    // Standard Vite config — your plugins just work
    return config
  },
  configureServer(app) {
    // Standard Express app — add any middleware
    app.use(cors())
  },
}

export default config

No framework magic. It's Vite and Express under the hood, both fully accessible.

The performance difference

We run automated benchmarks in CI comparing Pareto against Next.js on identical hardware:

Data loading throughput: Pareto 2,733 req/s vs Next.js 293 req/s (9.3x)
Streaming SSR capacity: Pareto 2,022 req/s vs Next.js 310 req/s (6.5x)
Client JS bundle: 62 KB vs 233 KB (73% smaller)

In infrastructure terms: a page serving 2,000 req/s needs 1 Pareto server vs 6 Next.js instances. Full benchmark details: paretojs.tech/blog/benchmarks

What you give up

Transparency matters. Here's what Pareto doesn't have:

Server components — No RSC, no "use client". This is by design: the loader pattern is simpler and covers 95% of use cases.
Image optimization — No <Image> component with automatic resizing. Use standard <img> with a CDN.
ISR / Static generation — Pareto is SSR-only. No generateStaticParams(), no build-time rendering. If you need static pages, pair with a static site generator.
Middleware — No edge middleware concept. Use Express middleware in configureServer() instead.
Vercel integration — No one-click deploy. You deploy a standard Node.js server.
Ecosystem size — Smaller community, fewer examples. You're early.

If you're building a content-heavy marketing site with ISR, Next.js is still the right call. If you're building a data-driven app where performance and simplicity matter, Pareto is worth the switch.

Migration checklist

npx create-pareto@latest my-app — scaffold a new project
Move your routes from app/ — file structure is nearly identical
Extract async server components into loader.ts + standard component
Replace "use client" directives — they're not needed, just delete them
Move generateMetadata to head.tsx components
Replace loading.tsx with defer() + <Await> for streaming
Replace next/link with Link from @paretojs/core
Move Webpack config to configureVite() in pareto.config.ts
Deploy as a standard Node.js server

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

Building Real-Time Features in React Without WebSocket Libraries

reactuse.com — Thu, 02 Apr 2026 02:57:15 +0000

Building Real-Time Features in React Without WebSocket Libraries

When developers hear "real-time," they reach for WebSocket libraries. Socket.IO, Pusher, Ably -- the ecosystem is full of them. But many real-time features do not need bidirectional communication. A stock ticker, a notification feed, a deployment log, a live sports score -- all of these are one-directional streams from server to client. For these use cases, the browser already has a built-in protocol that is simpler, lighter, and automatically reconnects: Server-Sent Events (SSE).

Combine SSE with the Network Information API for connection awareness, and the BroadcastChannel API for cross-tab coordination, and you have a complete real-time toolkit -- zero WebSocket libraries required. In this article, we will build each piece from scratch first, see where the manual approach breaks down, then replace it with hooks from ReactUse that handle all the edge cases in a few lines.

1. Server-Sent Events with useEventSource

What Are Server-Sent Events?

Server-Sent Events (SSE) is a standard that lets a server push updates to the browser over a plain HTTP connection. Unlike WebSockets, SSE is unidirectional -- the server sends, the client receives. The browser's native EventSource API handles connection management, automatic reconnection, and event parsing out of the box.

// A basic SSE endpoint (server side, for reference)
// GET /api/notifications
// Content-Type: text/event-stream
//
// data: {"message": "New deployment started"}
// id: 1
//
// data: {"message": "Deployment complete"}
// id: 2

The Manual Way

Let us connect to an SSE endpoint in React without any libraries.

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

function useManualEventSource(url: string) {
  const [data, setData] = useState<string | null>(null);
  const [status, setStatus] = useState<
    "CONNECTING" | "CONNECTED" | "DISCONNECTED"
  >("DISCONNECTED");
  const [error, setError] = useState<Event | null>(null);
  const esRef = useRef<EventSource | null>(null);
  const retriesRef = useRef(0);

  useEffect(() => {
    const connect = () => {
      setStatus("CONNECTING");
      const es = new EventSource(url);
      esRef.current = es;

      es.onopen = () => {
        setStatus("CONNECTED");
        setError(null);
        retriesRef.current = 0;
      };

      es.onmessage = (event) => {
        setData(event.data);
      };

      es.onerror = (err) => {
        setError(err);
        setStatus("DISCONNECTED");
        es.close();
        esRef.current = null;

        // Manual reconnection logic
        retriesRef.current += 1;
        if (retriesRef.current < 5) {
          setTimeout(connect, 1000 * retriesRef.current);
        }
      };
    };

    connect();

    return () => {
      esRef.current?.close();
      esRef.current = null;
    };
  }, [url]);

  return { data, status, error };
}

That is about 45 lines, and it already has problems:

Named events are not handled. SSE supports custom event types (e.g., event: deploy-status), but onmessage only catches unnamed messages. Supporting named events requires calling addEventListener for each event type and cleaning up each listener on unmount.
Reconnection is naive. The code retries up to 5 times with linear backoff, but there is no way to configure the limit, the delay, or a failure callback.
No explicit close/reopen. If the user navigates away and comes back, or if you want to pause the stream while the tab is hidden, you need more state tracking.
SSR will crash. EventSource does not exist on the server.

With useEventSource

The useEventSource hook from ReactUse handles all of this.

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

function DeploymentLog() {
  const { data, status, error, event, lastEventId, close, open } =
    useEventSource("/api/deployments/stream", ["deploy-start", "deploy-end"], {
      autoReconnect: {
        retries: 5,
        delay: 2000,
        onFailed: () => console.error("SSE connection permanently failed"),
      },
    });

  return (
    <div>
      <div>
        Status: {status}
        {status === "DISCONNECTED" && (
          <button onClick={open}>Reconnect</button>
        )}
        {status === "CONNECTED" && (
          <button onClick={close}>Disconnect</button>
        )}
      </div>

      {error && <div className="error">Connection error occurred</div>}

      <div className="log-entry">
        <span className="event-type">{event}</span>
        <span className="event-id">#{lastEventId}</span>
        <pre>{data}</pre>
      </div>
    </div>
  );
}

Look at what you get for free:

Named event support. Pass an array of event names as the second argument, and the hook listens to each one. The event return value tells you which event type fired.
Configurable auto-reconnect. Set the number of retries, the delay between attempts, and a callback when all retries are exhausted.
Explicit close and reopen. Call close() to disconnect, open() to reconnect -- useful for pausing streams in background tabs.
SSR safe. The hook guards against EventSource being undefined on the server.
Last event ID tracking. The lastEventId value lets you resume from where you left off if the server supports it.

A Practical Example: Live Notification Feed

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

interface Notification {
  id: string;
  title: string;
  body: string;
  severity: "info" | "warning" | "error";
}

function NotificationFeed() {
  const [notifications, setNotifications] = useState<Notification[]>([]);
  const { data, status, event } = useEventSource(
    "/api/notifications/stream",
    ["info", "warning", "error"],
    {
      autoReconnect: {
        retries: -1, // retry forever
        delay: 3000,
      },
    }
  );

  useEffect(() => {
    if (data) {
      try {
        const notification: Notification = {
          ...JSON.parse(data),
          severity: event as Notification["severity"],
        };
        setNotifications((prev) => [notification, ...prev].slice(0, 50));
      } catch {
        // malformed data, ignore
      }
    }
  }, [data, event]);

  return (
    <div>
      <h2>
        Live Notifications
        <span className={`status-dot status-${status.toLowerCase()}`} />
      </h2>
      {notifications.map((n) => (
        <div key={n.id} className={`notification notification-${n.severity}`}>
          <strong>{n.title}</strong>
          <p>{n.body}</p>
        </div>
      ))}
    </div>
  );
}

The hook handles the SSE lifecycle. Your component only deals with parsing data and rendering UI.

2. Authenticated SSE Streams with useFetchEventSource

The Problem with Native EventSource

The native EventSource API has a major limitation: you cannot set custom headers. That means no Authorization: Bearer <token>, no custom X-Request-ID, and no POST requests with a body. If your SSE endpoint requires authentication, EventSource is not enough.

The common workaround is to pass the token as a query parameter (/api/stream?token=abc), but that leaks credentials into server logs, browser history, and referrer headers. It is a security anti-pattern.

The Manual Way

To send headers with an SSE-like connection, you need to use fetch with a readable stream -- and handle chunked parsing, reconnection, and abort signals yourself.

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

function useManualFetchSSE(url: string, token: string) {
  const [data, setData] = useState<string | null>(null);
  const [status, setStatus] = useState<string>("DISCONNECTED");
  const abortRef = useRef<AbortController | null>(null);

  useEffect(() => {
    const controller = new AbortController();
    abortRef.current = controller;
    setStatus("CONNECTING");

    const connect = async () => {
      try {
        const response = await fetch(url, {
          headers: {
            Authorization: `Bearer ${token}`,
            Accept: "text/event-stream",
          },
          signal: controller.signal,
        });

        if (!response.ok) throw new Error(`HTTP ${response.status}`);
        if (!response.body) throw new Error("No response body");

        setStatus("CONNECTED");
        const reader = response.body.getReader();
        const decoder = new TextDecoder();
        let buffer = "";

        while (true) {
          const { done, value } = await reader.read();
          if (done) break;

          buffer += decoder.decode(value, { stream: true });
          const lines = buffer.split("\n\n");
          buffer = lines.pop() || "";

          for (const chunk of lines) {
            const dataLine = chunk
              .split("\n")
              .find((l) => l.startsWith("data: "));
            if (dataLine) {
              setData(dataLine.slice(6));
            }
          }
        }
      } catch (err) {
        if (!controller.signal.aborted) {
          setStatus("DISCONNECTED");
          // reconnection logic here...
        }
      }
    };

    connect();
    return () => controller.abort();
  }, [url, token]);

  return { data, status };
}

This is already 55+ lines, and it is incomplete. It does not handle named events, event IDs, reconnection with backoff, or POST requests. Parsing the SSE text protocol by hand is error-prone.

With useFetchEventSource

The useFetchEventSource hook wraps the @microsoft/fetch-event-source library in a React-friendly API. It supports custom headers, POST requests with bodies, and all the reconnection logic you need.

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

function AuthenticatedStream() {
  const { data, status, event, error, close, open } = useFetchEventSource(
    "/api/private/stream",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${getAccessToken()}`,
        "X-Request-ID": crypto.randomUUID(),
      },
      body: JSON.stringify({
        channels: ["deployments", "alerts"],
      }),
      autoReconnect: {
        retries: 10,
        delay: 2000,
        onFailed: () => {
          // Token might be expired -- redirect to login
          window.location.href = "/login";
        },
      },
      onOpen: () => console.log("Stream connected"),
      onError: (err) => {
        console.error("Stream error:", err);
        return 5000; // retry after 5 seconds
      },
    }
  );

  return (
    <div>
      <div>Connection: {status}</div>
      {error && <div className="error">{error.message}</div>}
      <pre>{data}</pre>
    </div>
  );
}

Key differences from useEventSource:

Feature	useEventSource	useFetchEventSource
Custom headers	No	Yes
POST requests	No	Yes
Request body	No	Yes
Based on	Native `EventSource`	`fetch` API
Auto-reconnect	Yes	Yes
Named events	Yes (via array)	Yes (via `event` field)

Use useEventSource when your endpoint is public or uses cookie-based auth. Use useFetchEventSource when you need token-based auth, custom headers, or POST requests.

A Practical Example: AI Chat Streaming

SSE is the standard protocol for streaming AI responses (OpenAI, Anthropic, and others all use it). Here is how to build a streaming chat UI with authentication.

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

function AIChatStream() {
  const [messages, setMessages] = useState<
    Array<{ role: string; content: string }>
  >([]);
  const [input, setInput] = useState("");
  const [streamedResponse, setStreamedResponse] = useState("");

  const { data, status, open, close } = useFetchEventSource(
    "/api/chat/completions",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${getApiKey()}`,
      },
      body: JSON.stringify({
        messages,
        stream: true,
      }),
      immediate: false, // don't connect on mount
      onOpen: () => setStreamedResponse(""),
    }
  );

  // Accumulate streamed tokens
  useEffect(() => {
    if (data) {
      try {
        const parsed = JSON.parse(data);
        const token = parsed.choices?.[0]?.delta?.content;
        if (token) {
          setStreamedResponse((prev) => prev + token);
        }
      } catch {
        // ignore [DONE] or malformed chunks
      }
    }
  }, [data]);

  const sendMessage = useCallback(() => {
    if (!input.trim()) return;
    setMessages((prev) => [...prev, { role: "user", content: input }]);
    setInput("");
    open(); // start the SSE stream
  }, [input, open]);

  return (
    <div className="chat">
      {messages.map((msg, i) => (
        <div key={i} className={`message message-${msg.role}`}>
          {msg.content}
        </div>
      ))}
      {streamedResponse && (
        <div className="message message-assistant">{streamedResponse}</div>
      )}
      <div className="input-row">
        <input
          value={input}
          onChange={(e) => setInput(e.target.value)}
          onKeyDown={(e) => e.key === "Enter" && sendMessage()}
          placeholder="Type a message..."
        />
        <button onClick={sendMessage} disabled={status === "CONNECTING"}>
          Send
        </button>
      </div>
    </div>
  );
}

The immediate: false option is critical here -- we do not want the connection to open on mount. We call open() explicitly when the user sends a message.

3. Network Status Detection with useNetwork and useOnline

Real-time features are useless if the user is offline. Worse, they fail silently -- the SSE connection drops, fetch requests hang, and the UI shows stale data without any indication that something is wrong. Good real-time UIs are network-aware.

The Manual Way

import { useState, useEffect } from "react";

function useManualNetworkStatus() {
  const [isOnline, setIsOnline] = useState(
    typeof navigator !== "undefined" ? navigator.onLine : true
  );
  const [connectionType, setConnectionType] = useState<string | undefined>();

  useEffect(() => {
    const handleOnline = () => setIsOnline(true);
    const handleOffline = () => setIsOnline(false);

    window.addEventListener("online", handleOnline);
    window.addEventListener("offline", handleOffline);

    // Network Information API (not available in all browsers)
    const conn = (navigator as any).connection;
    if (conn) {
      const handleChange = () => {
        setConnectionType(conn.effectiveType);
      };
      conn.addEventListener("change", handleChange);
      handleChange();

      return () => {
        window.removeEventListener("online", handleOnline);
        window.removeEventListener("offline", handleOffline);
        conn.removeEventListener("change", handleChange);
      };
    }

    return () => {
      window.removeEventListener("online", handleOnline);
      window.removeEventListener("offline", handleOffline);
    };
  }, []);

  return { isOnline, connectionType };
}

That is around 35 lines for just two pieces of information, and it does not track downlink speed, round-trip time, data saver mode, or the timestamp of the last status change. The Network Information API also uses vendor-prefixed properties (mozConnection, webkitConnection) that this code does not handle.

With useNetwork

The useNetwork hook returns the full picture.

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

function NetworkDebugPanel() {
  const {
    online,
    previous,
    since,
    downlink,
    effectiveType,
    rtt,
    saveData,
    type,
  } = useNetwork();

  return (
    <div className="network-panel">
      <div>
        Status: {online ? "Online" : "Offline"}
        {previous !== undefined && previous !== online && (
          <span>
            {" "}
            (was {previous ? "online" : "offline"}, changed{" "}
            {since?.toLocaleTimeString()})
          </span>
        )}
      </div>
      <div>Connection: {type ?? "unknown"}</div>
      <div>Effective type: {effectiveType ?? "unknown"}</div>
      <div>Downlink: {downlink ? `${downlink} Mbps` : "unknown"}</div>
      <div>RTT: {rtt ? `${rtt}ms` : "unknown"}</div>
      <div>Data saver: {saveData ? "enabled" : "disabled"}</div>
    </div>
  );
}

The hook handles all the vendor prefixes, event listeners, and SSR safety. The previous and since fields are especially useful -- they let you show "You went offline 30 seconds ago" instead of just "Offline."

With useOnline

If you only need the boolean, useOnline is even simpler. It is a thin wrapper around useNetwork that returns just the online value.

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

function OfflineBanner() {
  const isOnline = useOnline();

  if (isOnline) return null;

  return (
    <div className="offline-banner">
      You are offline. Real-time updates are paused.
    </div>
  );
}

A Practical Example: Adaptive Quality Streaming

The network information from useNetwork lets you adapt your application's behavior to the user's connection quality.

import { useNetwork } from "@reactuses/core";
import { useMemo } from "react";

function useAdaptivePolling(baseInterval: number) {
  const { online, effectiveType, saveData } = useNetwork();

  const interval = useMemo(() => {
    if (!online) return null; // stop polling when offline
    if (saveData) return baseInterval * 4; // respect data saver
    switch (effectiveType) {
      case "slow-2g":
      case "2g":
        return baseInterval * 3;
      case "3g":
        return baseInterval * 2;
      case "4g":
      default:
        return baseInterval;
    }
  }, [online, effectiveType, saveData, baseInterval]);

  return interval;
}

function LiveScoreboard() {
  const pollingInterval = useAdaptivePolling(5000);
  const { online, effectiveType } = useNetwork();

  return (
    <div>
      {!online && (
        <div className="banner">Offline -- showing cached scores</div>
      )}
      {effectiveType === "slow-2g" && (
        <div className="banner">Slow connection -- updates reduced</div>
      )}
      {/* Scoreboard content using pollingInterval */}
    </div>
  );
}

On a fast 4G connection, the scoreboard updates every 5 seconds. On a slow 2G connection, it updates every 15 seconds. Offline, it stops entirely and shows cached data. The user gets the best experience their connection can support.

4. Cross-Tab Communication with useBroadcastChannel

Real-time data often needs to be shared across browser tabs. If a user has your dashboard open in three tabs and a new notification arrives via SSE, all three tabs should show it -- but only one tab should maintain the SSE connection. The BroadcastChannel API makes this possible.

The Manual Way

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

function useManualBroadcastChannel<T>(channelName: string) {
  const [data, setData] = useState<T | undefined>();
  const channelRef = useRef<BroadcastChannel | null>(null);

  useEffect(() => {
    if (typeof BroadcastChannel === "undefined") return;

    const channel = new BroadcastChannel(channelName);
    channelRef.current = channel;

    const handleMessage = (event: MessageEvent<T>) => {
      setData(event.data);
    };

    const handleError = (event: MessageEvent) => {
      console.error("BroadcastChannel error:", event);
    };

    channel.addEventListener("message", handleMessage);
    channel.addEventListener("messageerror", handleError);

    return () => {
      channel.removeEventListener("message", handleMessage);
      channel.removeEventListener("messageerror", handleError);
      channel.close();
    };
  }, [channelName]);

  const post = useCallback((message: T) => {
    channelRef.current?.postMessage(message);
  }, []);

  return { data, post };
}

This works for simple cases, but it does not track whether BroadcastChannel is supported, whether the channel is closed, error state, or timestamps for deduplication.

With useBroadcastChannel

The useBroadcastChannel hook provides a complete, type-safe wrapper.

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

interface DashboardMessage {
  type: "NEW_DATA" | "USER_ACTION" | "TAB_CLOSING";
  payload?: unknown;
  sourceTab: string;
}

function DashboardSync() {
  const { data, post, isSupported, isClosed, error } = useBroadcastChannel<
    DashboardMessage,
    DashboardMessage
  >({ name: "dashboard-sync" });

  const broadcast = (type: DashboardMessage["type"], payload?: unknown) => {
    post({
      type,
      payload,
      sourceTab: sessionStorage.getItem("tab-id") || "unknown",
    });
  };

  useEffect(() => {
    if (data?.type === "NEW_DATA") {
      // Update local state with data from another tab
      console.log("Received data from tab:", data.sourceTab, data.payload);
    }
  }, [data]);

  if (!isSupported) {
    return <div>Cross-tab sync not available in this browser.</div>;
  }

  return (
    <div>
      <button onClick={() => broadcast("NEW_DATA", { count: 42 })}>
        Share data with other tabs
      </button>
      {error && <div className="error">Sync error</div>}
      {isClosed && <div className="warning">Channel closed</div>}
    </div>
  );
}

The hook gives you:

isSupported -- check if BroadcastChannel is available before rendering sync-dependent UI.
isClosed -- know when the channel has been closed (by you or by the browser).
error -- handle message serialization errors.
timeStamp -- deduplicate messages when the same data is received multiple times.
Type safety -- generic parameters <D, P> for received data type and posted data type.

5. Putting It All Together: A Real-Time Dashboard

Let us combine all five hooks into a production-style real-time dashboard. This dashboard:

Receives live metrics via SSE (with authentication)
Detects network status and adapts accordingly
Shares data across tabs so only one tab maintains the SSE connection
Shows connection health to the user

import {
  useFetchEventSource,
  useNetwork,
  useOnline,
  useBroadcastChannel,
  useEventSource,
} from "@reactuses/core";
import { useState, useEffect, useCallback, useRef } from "react";

// --- Types ---

interface MetricEvent {
  timestamp: number;
  cpu: number;
  memory: number;
  requests: number;
  errors: number;
}

interface TabMessage {
  type: "METRIC_UPDATE" | "CLAIM_LEADER" | "RELEASE_LEADER" | "HEARTBEAT";
  payload?: MetricEvent;
  tabId: string;
}

// --- Leader Election Hook ---

function useTabLeader(channelName: string) {
  const tabId = useRef(crypto.randomUUID()).current;
  const [isLeader, setIsLeader] = useState(false);
  const { data, post } = useBroadcastChannel<TabMessage, TabMessage>({
    name: channelName,
  });

  useEffect(() => {
    // On mount, claim leadership after a short delay
    const timer = setTimeout(() => {
      post({ type: "CLAIM_LEADER", tabId });
      setIsLeader(true);
    }, Math.random() * 200);

    return () => {
      clearTimeout(timer);
      post({ type: "RELEASE_LEADER", tabId });
    };
  }, [post, tabId]);

  useEffect(() => {
    if (data?.type === "CLAIM_LEADER" && data.tabId !== tabId) {
      if (data.tabId > tabId) {
        setIsLeader(false);
      }
    }
    if (data?.type === "RELEASE_LEADER") {
      // Another tab released -- try to claim
      setTimeout(() => {
        post({ type: "CLAIM_LEADER", tabId });
        setIsLeader(true);
      }, Math.random() * 100);
    }
  }, [data, tabId, post]);

  return { isLeader, tabId };
}

// --- Network-Aware SSE Hook ---

function useMetricsStream(enabled: boolean) {
  const { online, effectiveType } = useNetwork();

  const { data, status, error, close, open } = useFetchEventSource(
    "/api/metrics/stream",
    {
      headers: {
        Authorization: `Bearer ${getAccessToken()}`,
      },
      immediate: false,
      autoReconnect: {
        retries: -1,
        delay: effectiveType === "4g" ? 2000 : 5000,
        onFailed: () => console.error("Metrics stream failed permanently"),
      },
    }
  );

  // Connect/disconnect based on enabled flag and online status
  useEffect(() => {
    if (enabled && online) {
      open();
    } else {
      close();
    }
  }, [enabled, online, open, close]);

  return { data, status, error };
}

// --- Main Dashboard Component ---

function RealtimeDashboard() {
  const [metrics, setMetrics] = useState<MetricEvent[]>([]);
  const isOnline = useOnline();
  const { online, effectiveType, rtt } = useNetwork();

  // Leader election -- only the leader tab opens the SSE connection
  const { isLeader, tabId } = useTabLeader("metrics-leader");

  // SSE stream -- only active if this tab is the leader
  const { data: sseData, status: sseStatus } = useMetricsStream(isLeader);

  // Cross-tab data sharing
  const { data: tabData, post: broadcastToTabs } = useBroadcastChannel<
    TabMessage,
    TabMessage
  >({ name: "metrics-data" });

  // When the leader receives SSE data, broadcast it to other tabs
  useEffect(() => {
    if (isLeader && sseData) {
      try {
        const metric: MetricEvent = JSON.parse(sseData);
        setMetrics((prev) => [...prev, metric].slice(-100));
        broadcastToTabs({
          type: "METRIC_UPDATE",
          payload: metric,
          tabId,
        });
      } catch {
        // malformed data
      }
    }
  }, [isLeader, sseData, broadcastToTabs, tabId]);

  // When a non-leader tab receives broadcast data, update local state
  useEffect(() => {
    if (!isLeader && tabData?.type === "METRIC_UPDATE" && tabData.payload) {
      setMetrics((prev) => [...prev, tabData.payload!].slice(-100));
    }
  }, [isLeader, tabData]);

  const latestMetric = metrics[metrics.length - 1];

  return (
    <div className="dashboard">
      {/* Connection Status Bar */}
      <header className="status-bar">
        <div className="status-indicators">
          <span className={`dot ${isOnline ? "green" : "red"}`} />
          <span>
            {isOnline ? "Online" : "Offline"}
            {effectiveType && ` (${effectiveType})`}
            {rtt && ` -- ${rtt}ms RTT`}
          </span>
        </div>
        <div className="tab-info">
          {isLeader ? "Leader tab (SSE active)" : "Follower tab (via broadcast)"}
          <span className={`dot ${sseStatus === "CONNECTED" ? "green" : "yellow"}`} />
        </div>
      </header>

      {/* Offline Banner */}
      {!isOnline && (
        <div className="offline-banner">
          You are offline. Showing the last {metrics.length} cached metrics.
          Data will resume when your connection is restored.
        </div>
      )}

      {/* Metrics Grid */}
      {latestMetric && (
        <div className="metrics-grid">
          <MetricCard
            label="CPU Usage"
            value={`${latestMetric.cpu.toFixed(1)}%`}
            status={latestMetric.cpu > 80 ? "danger" : "normal"}
          />
          <MetricCard
            label="Memory"
            value={`${latestMetric.memory.toFixed(1)}%`}
            status={latestMetric.memory > 90 ? "danger" : "normal"}
          />
          <MetricCard
            label="Requests/sec"
            value={latestMetric.requests.toLocaleString()}
            status="normal"
          />
          <MetricCard
            label="Errors/sec"
            value={latestMetric.errors.toLocaleString()}
            status={latestMetric.errors > 10 ? "danger" : "normal"}
          />
        </div>
      )}

      {/* Sparkline Chart (last 100 data points) */}
      <div className="chart-section">
        <h3>CPU Over Time</h3>
        <div className="sparkline">
          {metrics.map((m, i) => (
            <div
              key={i}
              className="bar"
              style={{
                height: `${m.cpu}%`,
                backgroundColor: m.cpu > 80 ? "#ef4444" : "#22c55e",
              }}
            />
          ))}
        </div>
      </div>
    </div>
  );
}

function MetricCard({
  label,
  value,
  status,
}: {
  label: string;
  value: string;
  status: "normal" | "danger";
}) {
  return (
    <div className={`metric-card metric-${status}`}>
      <div className="metric-label">{label}</div>
      <div className="metric-value">{value}</div>
    </div>
  );
}

Here is what each hook contributes to this dashboard:

useFetchEventSource -- connects to the authenticated metrics SSE endpoint with automatic reconnection.
useEventSource -- could be used instead if the endpoint does not require auth headers (swap it in with zero API changes to the component).
useNetwork -- provides connection quality data (effectiveType, rtt) for the status bar and adaptive reconnection delays.
useOnline -- drives the offline banner and pauses the SSE connection when the network drops.
useBroadcastChannel -- enables leader election and cross-tab data sharing, so only one tab maintains the SSE connection while all tabs show live data.

The result is a dashboard that:

Uses a single SSE connection across all tabs (saving server resources)
Automatically reconnects with adaptive backoff based on connection quality
Shows real-time network status to the user
Degrades gracefully when offline
Shares data instantly across every open tab

When to Use Which Hook

Scenario	Hook	Why
Public SSE endpoint	`useEventSource`	Simple, native EventSource
SSE with auth headers	`useFetchEventSource`	Custom headers via fetch
SSE with POST body	`useFetchEventSource`	Supports request bodies
Simple online/offline check	`useOnline`	Returns a single boolean
Detailed connection info	`useNetwork`	Downlink, RTT, effective type
Cross-tab messaging	`useBroadcastChannel`	In-memory, no persistence
Cross-tab + persistence	`useBroadcastChannel` + `useLocalStorage`	Best of both

Installation

npm install @reactuses/core

Or with your preferred package manager:

pnpm add @reactuses/core
yarn add @reactuses/core

Related Hooks

useEventSource -- reactive Server-Sent Events with named event support and auto-reconnect
useFetchEventSource -- SSE via fetch, supporting custom headers, POST requests, and authentication
useNetwork -- detailed network status including connection type, downlink speed, and RTT
useOnline -- simple boolean for online/offline detection
useBroadcastChannel -- type-safe cross-tab messaging via the BroadcastChannel API
useDocumentVisibility -- track whether the current tab is visible
useLocalStorage -- persistent state with automatic cross-tab synchronization

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

We Benchmarked Our SSR Framework Against Next.js — Here's What We Found

reactuse.com — Wed, 01 Apr 2026 04:15:53 +0000

We built Pareto, a lightweight streaming-first React SSR framework on Vite. Claims are cheap — so we built an automated benchmark suite that runs in CI on every PR, comparing Pareto against Next.js, React Router (Remix), and TanStack Start on identical hardware.

What We Tested

Four scenarios covering the most common SSR workloads:

Static SSR — Page with inline data, no async loader. Pure SSR throughput.
Data Loading — Loader with simulated 10ms DB query. SSR + data fetching overhead.
Streaming SSR — defer() + Suspense with 200ms delayed data. Streaming pipeline efficiency.
API / JSON — Pure JSON endpoint. Routing + serialization overhead.

All benchmarks on GitHub Actions (Ubuntu, Node 22, 4 CPUs), using autocannon with 100 connections for 30 seconds.

Throughput: Requests Per Second

Scenario	Pareto	Next.js	React Router	TanStack Start
Static SSR	2,224/s	3,328/s	997/s	2,009/s
Data Loading	2,733/s	293/s	955/s	1,386/s
Streaming SSR	247/s	236/s	247/s	247/s
API / JSON	3,675/s	2,212/s	1,950/s	—

Next.js wins on static SSR. But the moment a loader is involved, Pareto handles 9.3x more requests than Next.js and 2.9x more than React Router.

Load Capacity: Max Sustainable QPS

We ran a ramp-up test from 1 to 1,000 concurrent connections, measuring the max QPS each framework sustains while keeping p99 latency under 500ms.

Scenario	Pareto	Next.js	React Router	TanStack Start
Static SSR	2,281/s	2,203/s	1,098/s	1,515/s
Data Loading	2,735/s	331/s	1,044/s	1,458/s
Streaming SSR	2,022/s	310/s	807/s	960/s
API / JSON	3,556/s	1,419/s	1,912/s	—

Under streaming SSR load, Pareto sustains 2,022 req/s — that's 6.5x Next.js and 2.5x React Router.

What this looks like in practice: Say your product page needs to serve 2,000 req/s at peak. With Pareto, that's a single server. With Next.js at 331/s, you'd need 6 servers behind a load balancer. For streaming SSR dashboards, it's 1 Pareto instance vs 7 Next.js instances.

Latency

Scenario	Pareto p50/p99	Next.js p50/p99	React Router p50/p99
Static SSR	431ms / 1.35s	244ms / 326ms	704ms / 7.16s
Data Loading	350ms / 702ms	1.42s / 7.82s	760ms / 7.41s
API / JSON	266ms / 320ms	283ms / 321ms	486ms / 2.12s

Under 100 concurrent connections, Pareto's data loading p99 is 702ms while Next.js spikes to 7.82s. 99% of users get their page in under 700ms with Pareto. With Next.js, 1 in 100 users waits nearly 8 seconds.

Bundle Size

Framework	Client JS (gzip)	Total (gzip)
Pareto	62 KB	72 KB
Next.js	233 KB	409 KB
React Router	100 KB	102 KB
TanStack Start	101 KB	272 KB

62 KB of client JavaScript — roughly 1/4 of Next.js. On 4G mobile (~5 Mbps), that's 100ms to download vs 370ms. On 3G, it's 330ms vs 1.2 seconds before any rendering begins.

The Cost Difference

Here's a concrete scenario — a SaaS dashboard at 10,000 data-loading req/s peak:

Framework	Servers needed (4 CPU)	Monthly cost (est.)
Pareto	4	~$160
TanStack Start	7	~$280
React Router	10	~$400
Next.js	31	~$1,240

How We Keep Benchmarks Honest

CI automated — runs on every PR touching core code
System tuning — ASLR disabled, CPU governor performance
Median aggregation — eliminates outlier noise, CV% for stability
Sequential isolation — one framework at a time, cooldown between runs
Same hardware — all frameworks on the same GitHub Actions runner

The full suite is open source: github.com/childrentime/pareto/tree/main/benchmarks

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

Pareto is a lightweight, streaming-first React SSR framework built on Vite. GitHub · Docs

React Scroll Effects Without External Libraries

reactuse.com — Tue, 31 Mar 2026 01:47:13 +0000

React Scroll Effects Without External Libraries

Scroll is the most fundamental user interaction on the web. Progress bars that fill as you read, headers that shrink and stick, modals that lock the page behind them, "scroll to section" buttons -- these effects appear on nearly every modern site. Yet implementing them correctly in React means juggling addEventListener, IntersectionObserver, overflow styles, and a surprising number of edge cases. Most developers either pull in a heavy animation library or spend hours writing brittle imperative code.

This post takes a different path. We will tackle six common scroll scenarios, starting each time with the manual implementation so you understand the mechanics, then replacing it with a purpose-built hook from ReactUse (@reactuses/core). ReactUse is an open-source collection of 100+ React hooks that wrap common browser and element interactions into simple, composable APIs. By the end you will have a toolkit of composable, SSR-safe hooks that handle scroll tracking, scroll locking, smooth scrolling, sticky detection, visibility detection, and intersection observing -- all without a single external animation or scroll library.

1. Tracking Scroll Position

The Manual Way

Tracking how far a user has scrolled seems straightforward until you account for throttling, direction detection, and knowing when the user has reached the edges.

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

function ManualScrollTracker() {
  const containerRef = useRef<HTMLDivElement>(null);
  const [scrollY, setScrollY] = useState(0);
  const [direction, setDirection] = useState<"up" | "down">("down");
  const lastY = useRef(0);

  useEffect(() => {
    const el = containerRef.current;
    if (!el) return;

    const onScroll = () => {
      const y = el.scrollTop;
      setDirection(y > lastY.current ? "down" : "up");
      lastY.current = y;
      setScrollY(y);
    };

    el.addEventListener("scroll", onScroll, { passive: true });
    return () => el.removeEventListener("scroll", onScroll);
  }, []);

  const progress = containerRef.current
    ? scrollY /
      (containerRef.current.scrollHeight - containerRef.current.clientHeight)
    : 0;

  return (
    <div>
      <div
        style={{
          position: "fixed",
          top: 0,
          left: 0,
          height: 4,
          width: `${progress * 100}%`,
          background: "#4f46e5",
          transition: "width 0.1s",
        }}
      />
      <div
        ref={containerRef}
        style={{ height: "100vh", overflow: "auto" }}
      >
        {/* long content */}
      </div>
    </div>
  );
}

This gets the job done for a simple progress bar. But it does not tell you whether the user has reached the bottom, it has no horizontal scroll tracking, and the direction detection is naive (a single-pixel bounce during momentum scroll will flip it). Adding "arriving at edge" thresholds means even more state and math.

With useScroll

useScroll returns the current x and y offsets, scroll direction on both axes, plus boolean isScrolling and arrivedState fields that tell you whether the user has reached the top, bottom, left, or right edge.

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

function ScrollTracker() {
  const containerRef = useRef<HTMLDivElement>(null);

  const [position, direction, arrivedState, isScrolling] = useScroll(
    containerRef,
    { throttle: 50 }
  );

  const el = containerRef.current;
  const progress = el
    ? position.y / (el.scrollHeight - el.clientHeight)
    : 0;

  return (
    <div>
      {/* Progress bar */}
      <div
        style={{
          position: "fixed",
          top: 0,
          left: 0,
          height: 4,
          width: `${Math.min(progress * 100, 100)}%`,
          background: "#4f46e5",
          zIndex: 50,
        }}
      />

      {/* Scroll info overlay */}
      <div
        style={{
          position: "fixed",
          bottom: 16,
          right: 16,
          padding: "8px 16px",
          background: "#1e293b",
          color: "#fff",
          borderRadius: 8,
          fontSize: 14,
          zIndex: 50,
        }}
      >
        <div>Y: {Math.round(position.y)}px</div>
        <div>Direction: {direction.y ?? "none"}</div>
        <div>
          {arrivedState.bottom
            ? "You reached the bottom!"
            : isScrolling
              ? "Scrolling..."
              : "Idle"}
        </div>
      </div>

      <div
        ref={containerRef}
        style={{ height: "100vh", overflow: "auto" }}
      >
        {Array.from({ length: 100 }, (_, i) => (
          <p key={i} style={{ padding: "8px 16px" }}>
            Paragraph {i + 1}
          </p>
        ))}
      </div>
    </div>
  );
}

One hook call replaces all the manual event wiring, direction tracking, and edge detection. The built-in throttle option keeps performance smooth even on rapid-fire scroll events.

2. Locking Scroll for Modals

The Manual Way

When you open a modal, you need to prevent the page behind it from scrolling. The classic approach is to toggle overflow: hidden on the body:

import { useEffect, useState } from "react";

function ManualModal() {
  const [isOpen, setIsOpen] = useState(false);

  useEffect(() => {
    if (isOpen) {
      const scrollY = window.scrollY;
      document.body.style.position = "fixed";
      document.body.style.top = `-${scrollY}px`;
      document.body.style.width = "100%";
      document.body.style.overflow = "hidden";

      return () => {
        document.body.style.position = "";
        document.body.style.top = "";
        document.body.style.width = "";
        document.body.style.overflow = "";
        window.scrollTo(0, scrollY);
      };
    }
  }, [isOpen]);

  return (
    <>
      <button onClick={() => setIsOpen(true)}>Open Modal</button>
      {isOpen && (
        <div
          style={{
            position: "fixed",
            inset: 0,
            background: "rgba(0,0,0,0.5)",
            display: "flex",
            alignItems: "center",
            justifyContent: "center",
            zIndex: 100,
          }}
        >
          <div
            style={{
              background: "#fff",
              padding: 24,
              borderRadius: 12,
              maxWidth: 400,
            }}
          >
            <h2>Modal Title</h2>
            <p>The page behind this modal cannot scroll.</p>
            <button onClick={() => setIsOpen(false)}>Close</button>
          </div>
        </div>
      )}
    </>
  );
}

This works on desktop browsers, but the position: fixed trick causes the page to jump on iOS Safari if you don't carefully save and restore the scroll position. It also does not handle multiple overlapping modals or scrollable containers other than the body.

With useScrollLock

useScrollLock handles all these edge cases. Pass it a ref to the element you want to lock -- typically document.body -- and a boolean to control the lock state.

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

function Modal() {
  const [isOpen, setIsOpen] = useState(false);

  useScrollLock(
    typeof document !== "undefined" ? document.body : null,
    isOpen
  );

  return (
    <>
      <button onClick={() => setIsOpen(true)}>Open Modal</button>
      {isOpen && (
        <div
          style={{
            position: "fixed",
            inset: 0,
            background: "rgba(0,0,0,0.5)",
            display: "flex",
            alignItems: "center",
            justifyContent: "center",
            zIndex: 100,
          }}
        >
          <div
            style={{
              background: "#fff",
              padding: 24,
              borderRadius: 12,
              maxWidth: 400,
            }}
          >
            <h2>Modal Title</h2>
            <p>Scroll is locked. Try scrolling the page behind.</p>
            <button onClick={() => setIsOpen(false)}>Close</button>
          </div>
        </div>
      )}
    </>
  );
}

One line to lock, automatic unlock on unmount, SSR-safe with the document guard. The scroll position is preserved correctly across all browsers.

3. Smooth Scroll to a Section

The Manual Way

"Scroll to" buttons that jump to a section on the page are common in landing pages. The imperative approach:

import { useRef } from "react";

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

  const scrollToSection = () => {
    sectionRef.current?.scrollIntoView({
      behavior: "smooth",
      block: "start",
    });
  };

  return (
    <div>
      <nav style={{ position: "fixed", top: 0, padding: 16, zIndex: 10 }}>
        <button onClick={scrollToSection}>Go to Features</button>
      </nav>

      <div style={{ height: "100vh", background: "#f1f5f9" }}>
        <h1 style={{ paddingTop: 80 }}>Hero Section</h1>
      </div>

      <div ref={sectionRef} style={{ padding: 40 }}>
        <h2>Features</h2>
        <p>Feature content here...</p>
      </div>
    </div>
  );
}

scrollIntoView is fine for basic cases, but it does not let you control the easing curve, the scroll axis, or the offset (important when you have a fixed header that would overlap the target). There is also no way to know when the scrolling animation has completed.

With useScrollIntoView

useScrollIntoView gives you fine-grained control over the scroll animation, including custom duration, easing, axis, offset, and an onComplete callback.

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

function SmoothScrollPage() {
  const targetRef = useRef<HTMLDivElement>(null);

  const { scrollIntoView } = useScrollIntoView(targetRef, {
    duration: 800,
    offset: 80, // account for a fixed header
  });

  return (
    <div>
      <nav
        style={{
          position: "fixed",
          top: 0,
          left: 0,
          right: 0,
          height: 64,
          background: "#1e293b",
          display: "flex",
          alignItems: "center",
          padding: "0 24px",
          zIndex: 50,
        }}
      >
        <button
          onClick={() => scrollIntoView({ alignment: "start" })}
          style={{
            background: "#4f46e5",
            color: "#fff",
            border: "none",
            padding: "8px 16px",
            borderRadius: 6,
            cursor: "pointer",
          }}
        >
          Jump to Pricing
        </button>
      </nav>

      <div style={{ height: "150vh", paddingTop: 80 }}>
        <h1>Hero</h1>
        <p>Scroll down or click the button above.</p>
      </div>

      <div ref={targetRef} style={{ padding: 40, background: "#eef2ff" }}>
        <h2>Pricing</h2>
        <p>Plans and pricing details...</p>
      </div>

      <div style={{ height: "100vh" }} />
    </div>
  );
}

The offset option ensures the section appears below your fixed header rather than being hidden behind it. The smooth animation uses a configurable easing function, and the hook cleans up properly if the component unmounts mid-scroll.

4. Detecting Sticky Headers

The Manual Way

A common pattern is to change a header's appearance once it becomes sticky (adding a shadow, shrinking its height, etc.). Detecting this manually requires an IntersectionObserver with a sentinel element:

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

function ManualStickyHeader() {
  const sentinelRef = useRef<HTMLDivElement>(null);
  const [isStuck, setIsStuck] = useState(false);

  useEffect(() => {
    const sentinel = sentinelRef.current;
    if (!sentinel) return;

    const observer = new IntersectionObserver(
      ([entry]) => {
        setIsStuck(!entry.isIntersecting);
      },
      { threshold: 0 }
    );

    observer.observe(sentinel);
    return () => observer.disconnect();
  }, []);

  return (
    <div>
      {/* Sentinel: when this scrolls out of view, the header is stuck */}
      <div ref={sentinelRef} style={{ height: 1 }} />
      <header
        style={{
          position: "sticky",
          top: 0,
          padding: isStuck ? "8px 24px" : "16px 24px",
          background: isStuck ? "rgba(255,255,255,0.95)" : "#fff",
          boxShadow: isStuck ? "0 2px 8px rgba(0,0,0,0.1)" : "none",
          transition: "all 0.2s",
          zIndex: 40,
        }}
      >
        <h1 style={{ margin: 0, fontSize: isStuck ? 18 : 24 }}>
          My App
        </h1>
      </header>
      <main style={{ padding: 24 }}>
        {Array.from({ length: 80 }, (_, i) => (
          <p key={i}>Content paragraph {i + 1}</p>
        ))}
      </main>
    </div>
  );
}

This sentinel-based approach works but is fragile. You need to position the sentinel correctly, manage the observer lifecycle, and keep the sentinel in sync if the DOM structure changes.

With useSticky

useSticky handles sticky detection cleanly. It returns a boolean that flips to true when the element enters its stuck state.

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

function StickyHeader() {
  const headerRef = useRef<HTMLElement>(null);
  const [isStuck] = useSticky(headerRef);

  return (
    <div>
      <header
        ref={headerRef}
        style={{
          position: "sticky",
          top: 0,
          padding: isStuck ? "8px 24px" : "16px 24px",
          background: isStuck
            ? "rgba(255,255,255,0.95)"
            : "#fff",
          boxShadow: isStuck
            ? "0 2px 8px rgba(0,0,0,0.1)"
            : "none",
          transition: "all 0.2s",
          zIndex: 40,
        }}
      >
        <h1 style={{ margin: 0, fontSize: isStuck ? 18 : 24 }}>
          My App
        </h1>
      </header>
      <main style={{ padding: 24 }}>
        {Array.from({ length: 80 }, (_, i) => (
          <p key={i}>Content paragraph {i + 1}</p>
        ))}
      </main>
    </div>
  );
}

No sentinel elements. No manual observer setup. The hook does the detection internally and gives you a single reactive boolean to drive your styles.

5. Revealing Elements on Scroll

The Manual Way

Fade-in-on-scroll effects are everywhere. The standard approach is to set up an IntersectionObserver for each animated element:

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

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

  useEffect(() => {
    const el = ref.current;
    if (!el) return;

    const observer = new IntersectionObserver(
      ([entry]) => {
        if (entry.isIntersecting) {
          setIsVisible(true);
          observer.unobserve(el); // only animate once
        }
      },
      { threshold: 0.1 }
    );

    observer.observe(el);
    return () => observer.disconnect();
  }, []);

  return (
    <div
      ref={ref}
      style={{
        opacity: isVisible ? 1 : 0,
        transform: isVisible ? "translateY(0)" : "translateY(30px)",
        transition: "opacity 0.6s ease, transform 0.6s ease",
      }}
    >
      {children}
    </div>
  );
}

Copy-pasting this observer logic into every component that needs a reveal animation quickly becomes tedious.

With useElementVisibility

useElementVisibility wraps IntersectionObserver into a single boolean return value. Pair it with a useState flag to create one-time reveal effects:

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

function RevealOnScroll({ children }: { children: React.ReactNode }) {
  const ref = useRef<HTMLDivElement>(null);
  const [visible] = useElementVisibility(ref);
  const [hasRevealed, setHasRevealed] = useState(false);

  useEffect(() => {
    if (visible && !hasRevealed) {
      setHasRevealed(true);
    }
  }, [visible, hasRevealed]);

  return (
    <div
      ref={ref}
      style={{
        opacity: hasRevealed ? 1 : 0,
        transform: hasRevealed ? "translateY(0)" : "translateY(30px)",
        transition: "opacity 0.6s ease, transform 0.6s ease",
      }}
    >
      {children}
    </div>
  );
}

function FeaturePage() {
  return (
    <div style={{ padding: "100vh 24px 24px" }}>
      <RevealOnScroll>
        <h2>Feature One</h2>
        <p>This fades in when scrolled into view.</p>
      </RevealOnScroll>
      <div style={{ height: 200 }} />
      <RevealOnScroll>
        <h2>Feature Two</h2>
        <p>Each section animates independently.</p>
      </RevealOnScroll>
      <div style={{ height: 200 }} />
      <RevealOnScroll>
        <h2>Feature Three</h2>
        <p>And they only animate once -- no flickering on scroll back.</p>
      </RevealOnScroll>
    </div>
  );
}

useElementVisibility gives you the live visibility state. The hasRevealed flag ensures the animation only fires once. For repeating animations, simply drop the flag and drive the style directly from visible.

6. Advanced Intersection: Scroll-Linked Progress

The Manual Way

For more advanced scroll effects -- like a progress indicator that fills as you scroll through a specific section -- you need fine-grained intersection ratios:

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

function ManualSectionProgress() {
  const sectionRef = useRef<HTMLDivElement>(null);
  const [ratio, setRatio] = useState(0);

  useEffect(() => {
    const el = sectionRef.current;
    if (!el) return;

    const thresholds = Array.from({ length: 101 }, (_, i) => i / 100);
    const observer = new IntersectionObserver(
      ([entry]) => setRatio(entry.intersectionRatio),
      { threshold: thresholds }
    );

    observer.observe(el);
    return () => observer.disconnect();
  }, []);

  return (
    <div>
      <div style={{ height: "100vh" }} />
      <div ref={sectionRef} style={{ minHeight: "100vh", padding: 40 }}>
        <div
          style={{
            position: "sticky",
            top: 20,
            width: 200,
            height: 8,
            background: "#e2e8f0",
            borderRadius: 4,
          }}
        >
          <div
            style={{
              height: "100%",
              width: `${ratio * 100}%`,
              background: "#4f46e5",
              borderRadius: 4,
              transition: "width 0.1s",
            }}
          />
        </div>
        <h2>Long Section</h2>
        {Array.from({ length: 20 }, (_, i) => (
          <p key={i}>Paragraph {i + 1} of the section.</p>
        ))}
      </div>
      <div style={{ height: "100vh" }} />
    </div>
  );
}

Building 101 threshold steps and managing the observer manually is verbose. And if you want multiple observers with different root margins or targets, the boilerplate multiplies.

With useIntersectionObserver

useIntersectionObserver exposes the full IntersectionObserver API in a declarative way. You get the IntersectionObserverEntry directly, including intersectionRatio, isIntersecting, and boundingClientRect.

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

function SectionProgress() {
  const sectionRef = useRef<HTMLDivElement>(null);
  const [ratio, setRatio] = useState(0);

  useIntersectionObserver(
    sectionRef,
    ([entry]) => {
      setRatio(entry.intersectionRatio);
    },
    {
      threshold: Array.from({ length: 101 }, (_, i) => i / 100),
    }
  );

  return (
    <div>
      <div style={{ height: "100vh" }} />
      <div ref={sectionRef} style={{ minHeight: "100vh", padding: 40 }}>
        <div
          style={{
            position: "sticky",
            top: 20,
            width: 200,
            height: 8,
            background: "#e2e8f0",
            borderRadius: 4,
          }}
        >
          <div
            style={{
              height: "100%",
              width: `${ratio * 100}%`,
              background: "#4f46e5",
              borderRadius: 4,
              transition: "width 0.1s",
            }}
          />
        </div>
        <h2>Long Section</h2>
        {Array.from({ length: 20 }, (_, i) => (
          <p key={i}>Paragraph {i + 1} of the section.</p>
        ))}
      </div>
      <div style={{ height: "100vh" }} />
    </div>
  );
}

The hook manages the observer lifecycle, reconnects when options change, and cleans up on unmount. You focus on what to do with the intersection data, not how to wire the observer.

Putting It All Together

These hooks compose naturally. Here is a landing page skeleton that combines all six:

import {
  useScroll,
  useScrollLock,
  useScrollIntoView,
} from "@reactuses/core";
import { useSticky, useElementVisibility } from "@reactuses/core";
import { useRef, useState } from "react";

function LandingPage() {
  const scrollContainerRef = useRef<HTMLDivElement>(null);
  const pricingRef = useRef<HTMLDivElement>(null);
  const headerRef = useRef<HTMLElement>(null);

  // Track scroll for progress bar
  const [position] = useScroll(scrollContainerRef);

  // Sticky header detection
  const [isStuck] = useSticky(headerRef);

  // Smooth scroll to pricing
  const { scrollIntoView } = useScrollIntoView(pricingRef, {
    offset: 64,
  });

  // Modal with scroll lock
  const [modalOpen, setModalOpen] = useState(false);
  useScrollLock(
    typeof document !== "undefined" ? document.body : null,
    modalOpen
  );

  // Reveal pricing section
  const [pricingVisible] = useElementVisibility(pricingRef);

  const el = scrollContainerRef.current;
  const progress = el
    ? position.y / (el.scrollHeight - el.clientHeight)
    : 0;

  return (
    <div ref={scrollContainerRef} style={{ height: "100vh", overflow: "auto" }}>
      {/* Progress bar */}
      <div
        style={{
          position: "fixed",
          top: 0,
          left: 0,
          height: 3,
          width: `${Math.min(progress * 100, 100)}%`,
          background: "#4f46e5",
          zIndex: 60,
        }}
      />

      {/* Sticky header */}
      <header
        ref={headerRef}
        style={{
          position: "sticky",
          top: 0,
          padding: isStuck ? "8px 24px" : "16px 24px",
          background: "#fff",
          boxShadow: isStuck ? "0 2px 8px rgba(0,0,0,0.1)" : "none",
          transition: "all 0.2s",
          zIndex: 50,
          display: "flex",
          justifyContent: "space-between",
          alignItems: "center",
        }}
      >
        <span style={{ fontWeight: 700 }}>MyApp</span>
        <div style={{ display: "flex", gap: 12 }}>
          <button onClick={() => scrollIntoView()}>Pricing</button>
          <button onClick={() => setModalOpen(true)}>Contact</button>
        </div>
      </header>

      {/* Hero */}
      <section style={{ height: "100vh", padding: 40 }}>
        <h1>Build amazing products</h1>
      </section>

      {/* Pricing with reveal */}
      <section
        ref={pricingRef}
        style={{
          padding: 40,
          opacity: pricingVisible ? 1 : 0,
          transform: pricingVisible ? "none" : "translateY(30px)",
          transition: "all 0.6s ease",
        }}
      >
        <h2>Pricing</h2>
        <p>Plans and details here.</p>
      </section>

      <div style={{ height: "100vh" }} />

      {/* Modal */}
      {modalOpen && (
        <div
          style={{
            position: "fixed",
            inset: 0,
            background: "rgba(0,0,0,0.5)",
            display: "flex",
            alignItems: "center",
            justifyContent: "center",
            zIndex: 100,
          }}
        >
          <div
            style={{
              background: "#fff",
              padding: 24,
              borderRadius: 12,
              maxWidth: 400,
            }}
          >
            <h2>Contact Us</h2>
            <p>Page scroll is locked while this modal is open.</p>
            <button onClick={() => setModalOpen(false)}>Close</button>
          </div>
        </div>
      )}
    </div>
  );
}

Each hook handles one responsibility. They share refs naturally, do not conflict with each other, and all clean up automatically on unmount.

Installation

npm i @reactuses/core

Related Hooks

useScroll -- Track scroll position, direction, and edge arrival
useScrollLock -- Lock scroll on any element
useScrollIntoView -- Smooth scroll to a target element with offset and easing
useSticky -- Detect when an element enters its sticky state
useElementVisibility -- Check if an element is visible in the viewport
useIntersectionObserver -- Full-featured intersection observation
useEventListener -- Attach event listeners declaratively
useElementSize -- Track element dimensions reactively
useElementBounding -- Get live bounding rectangle of an element

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

Real-time React: Syncing State Across Browser Tabs

reactuse.com — Fri, 27 Mar 2026 00:49:00 +0000

Real-time React: Syncing State Across Browser Tabs

Your user logs out in one tab. In another tab, they are still browsing authenticated content. They change the theme to dark mode, but the other three tabs stay light. They add an item to their cart, switch tabs, and the cart count shows zero. These are not edge cases — they are everyday realities of multi-tab browsing, and most React applications handle them poorly or not at all.

Browsers do not share React state between tabs by default. Each tab runs its own JavaScript context with its own component tree, its own state, and its own memory. Yet users expect a seamless experience. When something changes in one tab, they expect every tab to reflect that change immediately.

In this article, we will explore the browser APIs that make cross-tab communication possible, look at the manual approach and its pitfalls, and then see how hooks from ReactUse reduce all of that complexity to a few lines of code.

Two Browser APIs for Cross-Tab Communication

Before reaching for any library, it helps to understand what the browser gives us natively.

BroadcastChannel API

The BroadcastChannel API lets you send messages between browsing contexts — tabs, windows, iframes — that share the same origin. You create a channel by name, and any context that opens a channel with the same name can send and receive messages.

// Tab A
const channel = new BroadcastChannel("my-app");
channel.postMessage({ type: "LOGOUT" });

// Tab B
const channel = new BroadcastChannel("my-app");
channel.onmessage = (event) => {
  if (event.data.type === "LOGOUT") {
    // redirect to login
  }
};

BroadcastChannel is fast, supports structured cloning (so you can send objects, arrays, and even ArrayBuffer), and does not touch persistent storage. It is purely in-memory messaging between contexts. The downside is that messages are fire-and-forget — if a tab is not open when the message is sent, it never receives it.

Storage Events

When one tab writes to localStorage, every other tab on the same origin receives a storage event. This gives you cross-tab reactivity for free — but only for string-serializable data, and only through localStorage (not sessionStorage, which is scoped to a single tab).

// Tab A writes
localStorage.setItem("theme", "dark");

// Tab B listens
window.addEventListener("storage", (event) => {
  if (event.key === "theme") {
    console.log("Theme changed to:", event.newValue); // "dark"
  }
});

Storage events have a major advantage: the data persists. If a user opens a new tab after the change was made, the new tab reads the current value from localStorage on mount. You get both reactivity and persistence.

The Manual Approach — And Why It Gets Messy

Let us try to build cross-tab theme syncing from scratch. We need to:

Read the initial value from localStorage.
Parse it (everything in localStorage is a string).
Set up a storage event listener to detect changes from other tabs.
Serialize and write back when the local tab changes the value.
Clean up the listener on unmount.

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

function useCrossTabTheme() {
  const [theme, setThemeState] = useState<"light" | "dark">(() => {
    try {
      const stored = localStorage.getItem("app-theme");
      return stored === "dark" ? "dark" : "light";
    } catch {
      return "light";
    }
  });

  // Listen for changes from other tabs
  useEffect(() => {
    const handler = (event: StorageEvent) => {
      if (event.key === "app-theme" && event.newValue) {
        setThemeState(event.newValue as "light" | "dark");
      }
    };
    window.addEventListener("storage", handler);
    return () => window.removeEventListener("storage", handler);
  }, []);

  // Write to localStorage when local state changes
  const setTheme = useCallback((value: "light" | "dark") => {
    setThemeState(value);
    try {
      localStorage.setItem("app-theme", value);
    } catch {
      // storage full or unavailable
    }
  }, []);

  return [theme, setTheme] as const;
}

That is about 30 lines for a single string value. Now imagine doing this for auth tokens, user preferences, cart state, and notification counts. Each one needs its own serialization logic, error handling, and cleanup. And we have not even touched BroadcastChannel yet — if we want to send structured messages (not just key-value strings), we need a second communication layer with its own setup and teardown.

This is where well-designed hooks eliminate boilerplate without hiding the underlying concepts.

useBroadcastChannel: Type-Safe Messaging Between Tabs

The useBroadcastChannel hook from ReactUse wraps the BroadcastChannel API in a clean, declarative interface. It handles channel creation, message listening, cleanup on unmount, and even SSR safety — all in a single call.

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

function NotificationSync() {
  const { data, post, error } = useBroadcastChannel<{
    type: string;
    payload?: unknown;
  }>("my-app-notifications");

  // Send a message to all other tabs
  const broadcastLogout = () => {
    post({ type: "LOGOUT" });
  };

  // React to messages from other tabs
  useEffect(() => {
    if (data?.type === "LOGOUT") {
      // Clear local auth state and redirect
      authStore.clear();
      window.location.href = "/login";
    }
  }, [data]);

  return <button onClick={broadcastLogout}>Log out everywhere</button>;
}

The generic type parameter gives you full TypeScript safety for the message shape. No manual serialization — BroadcastChannel uses structured cloning natively. No cleanup code — the hook closes the channel when the component unmounts. And the error value lets you handle the rare case where BroadcastChannel is not supported.

useLocalStorage: Automatic Cross-Tab Sync

For state that should persist and sync across tabs, useLocalStorage is the right tool. It works like useState, but the value is backed by localStorage and automatically stays in sync across all tabs via storage events.

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

function ThemeToggle() {
  const [theme, setTheme] = useLocalStorage<"light" | "dark">(
    "app-theme",
    "light"
  );

  return (
    <button onClick={() => setTheme(theme === "light" ? "dark" : "light")}>
      Current: {theme}
    </button>
  );
}

When setTheme is called in one tab, every other tab running this hook with the same key ("app-theme") updates automatically. The hook handles JSON serialization, initial value fallback, SSR guards, and storage event subscription internally. You write one line of hook usage; the hook writes thirty lines of browser API code for you.

Contrast this with useSessionStorage, which provides the same API but scopes the value to the current tab. Session storage does not fire cross-tab events and does not persist after the tab closes. Choose useLocalStorage when you want cross-tab sync; choose useSessionStorage when you want tab-isolated persistence.

Practical Patterns

Pattern 1: Syncing Auth State (Logout Everywhere)

One of the most critical cross-tab scenarios is authentication. When a user logs out in one tab, every other tab must react immediately — otherwise they might continue making authenticated requests that fail silently or expose stale data.

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

function useAuth() {
  const [token, setToken] = useLocalStorage<string | null>("auth-token", null);
  const { data, post } = useBroadcastChannel<{ type: "LOGOUT" | "LOGIN" }>(
    "auth-channel"
  );

  // Handle messages from other tabs
  useEffect(() => {
    if (data?.type === "LOGOUT") {
      setToken(null);
      window.location.href = "/login";
    }
  }, [data, setToken]);

  const login = (newToken: string) => {
    setToken(newToken);
    post({ type: "LOGIN" });
  };

  const logout = () => {
    setToken(null);
    post({ type: "LOGOUT" });
    window.location.href = "/login";
  };

  return { token, login, logout, isAuthenticated: token !== null };
}

This uses both hooks together: useLocalStorage persists the token and syncs it across tabs, while useBroadcastChannel sends an immediate imperative signal that triggers the redirect. The token sync via localStorage ensures any tab opened after the logout reads null. The broadcast ensures tabs open during the logout react instantly.

Pattern 2: Syncing Theme Across Tabs

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

function useThemeSync() {
  const [theme, setTheme] = useLocalStorage<"light" | "dark">(
    "app-theme",
    "light"
  );

  useEffect(() => {
    document.documentElement.setAttribute("data-theme", theme ?? "light");
  }, [theme]);

  return { theme: theme ?? "light", setTheme };
}

Because useLocalStorage already handles cross-tab sync, the useEffect fires in every tab whenever the theme changes — keeping the DOM attribute in sync everywhere.

Pattern 3: Cart State in E-Commerce

Shopping cart data is a classic candidate for cross-tab sync. Users often browse products in multiple tabs and expect the cart to be consistent.

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

interface CartItem {
  id: string;
  name: string;
  quantity: number;
  price: number;
}

function useCart() {
  const [items, setItems] = useLocalStorage<CartItem[]>("cart-items", []);

  const addItem = (item: Omit<CartItem, "quantity">) => {
    setItems((prev) => {
      const current = prev ?? [];
      const existing = current.find((i) => i.id === item.id);
      if (existing) {
        return current.map((i) =>
          i.id === item.id ? { ...i, quantity: i.quantity + 1 } : i
        );
      }
      return [...current, { ...item, quantity: 1 }];
    });
  };

  const removeItem = (id: string) => {
    setItems((prev) => (prev ?? []).filter((i) => i.id !== id));
  };

  const totalItems = (items ?? []).reduce((sum, i) => sum + i.quantity, 0);

  return { items: items ?? [], addItem, removeItem, totalItems };
}

Add an item in Tab A, and the cart badge updates in Tab B instantly. No WebSocket, no polling, no server round-trip.

Pattern 4: Leader Election

Sometimes you want only one tab to perform a task — polling an API, maintaining a WebSocket connection, or running a background sync. The useBroadcastChannel hook provides the messaging layer for a simple leader election protocol.

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

function useLeaderElection(channelName: string) {
  const [isLeader, setIsLeader] = useState(false);
  const idRef = useRef(Math.random().toString(36).slice(2));
  const { data, post } = useBroadcastChannel<{
    type: "CLAIM" | "HEARTBEAT" | "RELEASE";
    id: string;
  }>(channelName);

  useEffect(() => {
    // On mount, try to claim leadership
    post({ type: "CLAIM", id: idRef.current });
    const timer = setTimeout(() => setIsLeader(true), 200);

    return () => {
      clearTimeout(timer);
      post({ type: "RELEASE", id: idRef.current });
    };
  }, [post]);

  useEffect(() => {
    if (data?.type === "CLAIM" && data.id !== idRef.current) {
      // Another tab is claiming — compare IDs to break ties
      if (data.id > idRef.current) {
        setIsLeader(false);
      }
    }
  }, [data]);

  return isLeader;
}

Only the leader tab runs expensive operations. When it closes, it broadcasts a RELEASE message and another tab claims leadership.

Optimizing Background Tabs

Cross-tab sync is only part of the picture. When a tab is in the background, you often want to pause expensive work — polling APIs, running animations, or processing data. Two hooks from ReactUse make this straightforward.

useDocumentVisibility

useDocumentVisibility returns the current visibility state of the document — "visible" or "hidden". Use it to pause work when the tab is not visible.

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

function usePolling(url: string, intervalMs: number) {
  const visibility = useDocumentVisibility();
  const [data, setData] = useState(null);

  useEffect(() => {
    if (visibility === "hidden") return; // stop polling in background

    const fetchData = async () => {
      const res = await fetch(url);
      setData(await res.json());
    };

    fetchData();
    const id = setInterval(fetchData, intervalMs);
    return () => clearInterval(id);
  }, [url, intervalMs, visibility]);

  return data;
}

When the user switches away from the tab, the interval is cleared. When they switch back, a fresh interval starts. No wasted network requests while the tab is hidden.

useWindowFocus

useWindowFocus tracks whether the browser window itself has focus. This is subtler than visibility — a tab can be visible but unfocused (for example, when the user is interacting with DevTools or another window overlapping the browser).

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

function FocusIndicator() {
  const focused = useWindowFocus();

  return (
    <div>
      {focused
        ? "You are viewing this tab"
        : "Welcome back when you return!"}
    </div>
  );
}

Combine useDocumentVisibility and useWindowFocus for fine-grained control: pause non-critical work when the tab is hidden, and throttle less-critical work when the tab is visible but unfocused.

Combining Hooks: A Cross-Tab Notification System

Let us put it all together. Here is a notification system that broadcasts alerts across tabs, persists unread counts in localStorage, and pauses updates when the tab is hidden.

import {
  useBroadcastChannel,
  useLocalStorage,
  useDocumentVisibility,
  useOnline,
} from "@reactuses/core";
import { useEffect, useCallback } from "react";

interface Notification {
  id: string;
  title: string;
  body: string;
  timestamp: number;
}

function useNotificationSync() {
  const [notifications, setNotifications] = useLocalStorage<Notification[]>(
    "app-notifications",
    []
  );
  const [unreadCount, setUnreadCount] = useLocalStorage<number>(
    "unread-count",
    0
  );
  const { data, post } = useBroadcastChannel<{
    type: "NEW_NOTIFICATION" | "MARK_READ" | "CLEAR_ALL";
    notification?: Notification;
  }>("notification-channel");
  const visibility = useDocumentVisibility();
  const isOnline = useOnline();

  // Handle messages from other tabs
  useEffect(() => {
    if (!data) return;

    switch (data.type) {
      case "NEW_NOTIFICATION":
        if (data.notification) {
          setNotifications((prev) => [data.notification!, ...(prev ?? [])]);
          setUnreadCount((prev) => (prev ?? 0) + 1);
        }
        break;
      case "MARK_READ":
        setUnreadCount(0);
        break;
      case "CLEAR_ALL":
        setNotifications([]);
        setUnreadCount(0);
        break;
    }
  }, [data, setNotifications, setUnreadCount]);

  const addNotification = useCallback(
    (title: string, body: string) => {
      const notification: Notification = {
        id: crypto.randomUUID(),
        title,
        body,
        timestamp: Date.now(),
      };
      setNotifications((prev) => [notification, ...(prev ?? [])]);
      setUnreadCount((prev) => (prev ?? 0) + 1);
      post({ type: "NEW_NOTIFICATION", notification });
    },
    [post, setNotifications, setUnreadCount]
  );

  const markAllRead = useCallback(() => {
    setUnreadCount(0);
    post({ type: "MARK_READ" });
  }, [post, setUnreadCount]);

  // Auto-mark as read when tab becomes visible
  useEffect(() => {
    if (visibility === "visible" && (unreadCount ?? 0) > 0) {
      markAllRead();
    }
  }, [visibility, unreadCount, markAllRead]);

  return {
    notifications: notifications ?? [],
    unreadCount: unreadCount ?? 0,
    addNotification,
    markAllRead,
    isOnline,
  };
}

This hook uses four ReactUse hooks working together:

useBroadcastChannel sends real-time signals between tabs when notifications arrive or are read.
useLocalStorage persists the notification list and unread count so new tabs pick up the current state.
useDocumentVisibility automatically marks notifications as read when the user returns to a background tab.
useOnline (via useOnline) exposes the network status so the UI can indicate when the app is offline and notifications may be delayed.

Each hook handles one concern. Composed together, they form a complete system with persistence, real-time sync, visibility awareness, and network status — in under 70 lines.

When to Use Which Approach

Scenario	Recommended Hook	Why
Persisted state that syncs across tabs	`useLocalStorage`	Data survives refresh; storage events provide sync
Tab-scoped state that does not sync	`useSessionStorage`	Isolated per tab; no cross-tab events
Real-time imperative messages	`useBroadcastChannel`	Fast, supports structured data, no persistence overhead
Both persistence and instant messaging	`useLocalStorage` + `useBroadcastChannel`	Best of both: persist for new tabs, broadcast for open tabs
Pausing background work	`useDocumentVisibility` / `useWindowFocus`	Reduce unnecessary computation and network requests

Installation

npm install @reactuses/core

Or with your preferred package manager:

pnpm add @reactuses/core
yarn add @reactuses/core

Related Hooks

useBroadcastChannel — type-safe cross-tab messaging via the BroadcastChannel API
useLocalStorage — persistent state with automatic cross-tab synchronization
useSessionStorage — tab-scoped persistent state
useDocumentVisibility — track whether the current tab is visible
useWindowFocus — track whether the browser window has focus
useEventListener — declarative event listener management with automatic cleanup
useOnline — reactive network connectivity status

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

Originally published on ReactUse Blog