useSyncExternalStore: Subscribing to Outside Stores

New words in this topic, in plain English. Come back here whenever one feels fuzzy.

External store

Data that lives outside React and can change by itself, like navigator.onLine or a Zustand store.

subscribe

Your function that starts listening for changes, calls React's callback on each change, and returns a function that stops listening.

getSnapshot

Your function that returns the store's current value. It must return the same value until the store really changes.

Snapshot

The value of the store at one moment, as React reads it during a render.

Tearing

Different parts of the screen showing different versions of the same data at the same time.

Concurrent rendering

React's ability (since React 18) to pause a render, handle something urgent, and continue later.

getServerSnapshot

The value to use during server rendering and hydration, where browser APIs don't exist.

Hydration

React attaching event handlers and state to HTML that a server already rendered (Topic 20.6).

1. 1

   Add a third reader

   In the online example, add a component OfflineBanner that returns null when online and a red banner when offline, using the same useOnlineStatus(). Predict: does the store need any change? (No: every subscriber is notified.)

2. 2

   Select an object and watch it break

   In the cart example, change CartBadge to const { items } = useCart((s) => ({ items: s.items }));. Predict the console, then run. Then fix it by selecting s.items again, or by selecting the whole s (the store's own object, which is stable).

3. 3

   Fix the uncached snapshot

   In the third example, make getSnapshot return user, and add a function rename(name) { user = { ...user, name }; listeners.forEach((l) => l()); }. Call setTimeout(() => rename("Ravi"), 200) and check the page updates.

Errors are the best teachers. Make each change, read the error, guess what went wrong, then reveal the answer.

1. 1

   An external store is any data that lives outside React and can change by itself: navigator.onLine, window.matchMedia, localStorage, the URL, a WebSocket's latest message, or a state library such as Zustand or Redux (Phase 15). React's own state (useState, useReducer) lives inside React; an external store doesn't, so React can't see when it changes unless you tell it.

2. 2

   The hook takes two functions. **subscribe(callback)** starts listening for changes, calls callback whenever the store changes, and returns an unsubscribe function (just like an effect cleanup). **getSnapshot() returns the store's current value, called a snapshot**. React calls subscribe after the first commit, calls getSnapshot during every render, and when callback fires it calls getSnapshot again: if the result differs from the last one (compared with Object.is), the component re-renders.

3. 3

   Snapshots must be cached. getSnapshot is called often, and React compares results by identity. If it returns a new object or array every call (return { ...user } or items.filter(...)), React thinks the store changed every time, re-renders, gets yet another new object, and loops. In development React warns The result of getSnapshot should be cached to avoid an infinite loop and then fails with Maximum update depth exceeded. Return the same object until the data really changes: return a primitive (true, 42, a string), return the store's own state object (which the store replaces only on change), or cache the derived value yourself.

4. 4

   Tearing is when different parts of the screen show different versions of the same data at once, like a torn photo whose two halves don't match. Since React 18, rendering can be concurrent: React may pause a big render to handle a click, then continue. If an outside store changes during that pause, components rendered before the pause read the old value and those rendered after read the new one, and the committed screen disagrees with itself. useSyncExternalStore prevents this: React checks the snapshot again before committing, and if the store changed during the render, it re-renders synchronously (without pausing) so every component sees one value. That's the "Sync" in the name.

5. 5

   **getServerSnapshot is the optional third argument. During server rendering (Topic 20.1) and hydration** (when React attaches to server-made HTML in the browser, Topic 20.6) there is no navigator or window, and the HTML must match what the server sent. React calls getServerSnapshot on the server and during hydration, then switches to getSnapshot and re-renders if the real value differs. Without it, server rendering a component that uses the hook throws Missing getServerSnapshot, which is required for server-rendered content. Will revert to client rendering. Return a safe default, the same on server and client (for example, true for online).

6. 6

   Use it for reading browser APIs (online status, media queries, page visibility, storage), and when writing your own store or wrapping a non-React library. Prefer it over the useState + useEffect subscription from Topic 10.2: that version reads the value once at first render, can miss a change that happens between render and the effect's subscription, and can tear under concurrent rendering. You rarely call it directly in app code: libraries such as Zustand, Redux (react-redux) and TanStack Query use it inside. Updates caused by an external store are always synchronous: they can't be marked as transitions (Topic 16.7), so a slow store-driven render can block typing.

• ↔

  useSyncExternalStore guarantees consistency by giving up concurrency for store updates: they always render synchronously. For huge trees driven by a fast-changing store, that can block input; deferring the value or keeping state in React may be smoother.

• ↔

  A homemade store is tiny and dependency-free, but you must handle selectors, equality and devtools yourself. Past a few stores, a library like Zustand (Topic 15.3) is the same idea with those parts done.

• I can write subscribe and getSnapshot for a browser API.

• I keep subscribe stable and return cached or primitive snapshots.

• I can explain tearing and how this hook prevents it.

• I add getServerSnapshot whenever a component may render on a server.

• I can build a small store that several components read with selectors.