React Reference ยท State Hooks
React useSyncExternalStore hook
Reference for React useSyncExternalStore: subscribe to data that lives outside React, with subscribe and getSnapshot rules, server snapshots and pitfalls.
useSyncExternalStore lets a component read data that React does not own: a small global store, a browser API such as matchMedia, or the state of a third-party library. It subscribes to the source, reads a snapshot, and re-renders the component whenever the snapshot changes.
It exists because naive solutions (copying the value into state in an effect) can show stale or torn values during concurrent rendering. This hook guarantees that every component rendered in one pass sees the same snapshot. State libraries use it internally; you reach for it when you write your own store or wrap a browser API.
const snapshot = useSyncExternalStore(subscribe, getSnapshot);
Try it
Both displays stay in sync because they read the same snapshot from the same store.
Syntax
const snapshot = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot?);
function useSyncExternalStore<T>( subscribe: (onStoreChange: () => void) => () => void, getSnapshot: () => T, getServerSnapshot?: () => T ): T;
| Name | Description |
|---|---|
subscribe |
Receives a callback, registers it with the store and returns a function that unsubscribes. Call that callback whenever the store changes. |
getSnapshot |
Returns the current value of the store. Must return the same value (by Object.is) as long as the store has not changed. |
getServerSnapshot |
Optional. Returns the initial value during server rendering and hydration. Required when rendering on the server. |
Returns: the current snapshot.
Errors / edge cases: if getSnapshot returns a different value on two consecutive calls without a store change (for example it builds a new object each time), React warns and may loop forever. Omitting getServerSnapshot while server rendering throws an error.
Usage notes
- Snapshots must be immutable and cached. Replace objects instead of mutating them, and compute derived values outside
getSnapshotor cache them. Returning{ a: store.a }freshly each time is the classic bug. - Keep
subscribestable. If you define it inline in the component, React unsubscribes and resubscribes on every render. Define it at module level or wrap it inuseCallback. - Selecting a piece: return a primitive (
state.count) fromgetSnapshotto avoid re-rendering when unrelated parts change. - Always check the snapshot after subscribing. React does this for you, which is how it catches changes that happen between render and subscribe.
- Updates are synchronous. A store change forces a synchronous re-render, so it cannot be marked as a non-blocking transition.
- Browser APIs: wrap events such as
online/offlineormatchMediachange events assubscribe, and readnavigator.onLineormql.matchesingetSnapshot; provide a server snapshot for SSR. - Prefer state or context for data that React already owns; this hook is for sources outside React.
Related
- useState, useContext, useEffect
- Lessons: External stores, State management