useSyncExternalStore

The signature is three functions: subscribe, getSnapshot, and (for SSR) getServerSnapshot. subscribe(cb) registers a callback React calls whenever the store changes, and returns an unsubscribe function. getSnapshot() returns the current value synchronously. getServerSnapshot() returns the value to use during server rendering and the initial client hydration, where browser APIs don’t exist.

"use client";
import { useSyncExternalStore } from "react";

function useOnlineStatus(): boolean {
  return useSyncExternalStore(
    // subscribe: wire store -> React, return cleanup
    (onStoreChange) => {
      window.addEventListener("online", onStoreChange);
      window.addEventListener("offline", onStoreChange);
      return () => {
        window.removeEventListener("online", onStoreChange);
        window.removeEventListener("offline", onStoreChange);
      };
    },
    () => navigator.onLine,        // getSnapshot (client)
    () => true,                    // getServerSnapshot (no navigator on the server)
  );
}

React subscribes once, reads the snapshot on every render, and re-renders the component when onStoreChange fires. No effect, no mirrored useState, no stale first render.

Why not useEffect + useState? Because that mirror tears under concurrent rendering and is stale on first paint. The effect runs after the first commit, so the first render shows whatever default you seeded, not the real value. Worse, because the value lives in your own state copy, a concurrent render that started before an update can commit an old value while another part of the tree commits the new one — the same store read two different things. useSyncExternalStore reads the snapshot synchronously during render and forces a consistent, non-torn read across the whole commit.

// ❌ the reflex: subscribe-in-effect, mirror into state
function useOnlineStatusBad() {
  const [online, setOnline] = useState(navigator.onLine); // crashes on the server too
  useEffect(() => {
    const on = () => setOnline(navigator.onLine);
    window.addEventListener("online", on);
    window.addEventListener("offline", on);
    return () => {
      window.removeEventListener("online", on);
      window.removeEventListener("offline", on);
    };
  }, []);
  return online; // stale before the effect runs; can tear under concurrent renders
}

This is also why React’s own docs list it under “you might not need an effect”: subscribing to an external store is exactly the case where the effect-mirror is the wrong tool and this hook is the right one.

getSnapshot MUST return a stable reference for unchanged data — a fresh object every call is an infinite render loop. After each render React calls getSnapshot and compares the result to the last one with Object.is. If it’s a new value, React assumes the store changed and re-renders — which calls getSnapshot again — which returns yet another new object — forever. The fix is to return the same reference until the underlying data actually changes (cache it in the store), or select a primitive.

// ❌ new array identity every call -> Object.is is always false -> loop
const todos = useSyncExternalStore(store.subscribe, () => store.todos.filter(t => !t.done));

// ✅ return a cached reference; recompute only when the store mutates
const todos = useSyncExternalStore(store.subscribe, store.getVisibleTodos);
// where getVisibleTodos memoises and only produces a new array when todos change

// ✅ or read a primitive, which is compared by value
const count = useSyncExternalStore(store.subscribe, () => store.todos.length);

If you genuinely need a derived object per render, derive it outside the hook with useMemo from a stable snapshot — never inside getSnapshot. (useSyncExternalStoreWithSelector from use-sync-external-store/shim/with-selector exists for exactly the select-and-compare case.)

Omit getServerSnapshot in any SSR/RSC-client app and you crash the server render. During server rendering and the first hydration pass there is no window or navigator, so getSnapshot throws (navigator is not defined) — or, if it doesn’t throw, the server HTML and the client’s first render disagree and you get a hydration mismatch. getServerSnapshot supplies a safe, deterministic value for the server and hydration; React then re-reads getSnapshot after mount and updates if the real value differs.

return useSyncExternalStore(
  subscribe,
  () => navigator.onLine,  // client snapshot — browser only
  () => true,              // server snapshot — assume online during SSR/hydration
);

In Next.js App Router this hook only runs in a "use client" component, but client components are still server-rendered for the initial HTML, so the third argument is not optional in that world — it’s the difference between a clean hydration and a runtime crash on first request.