Skip to content
Tutorials Center
My learning

Topics

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.

JSX
const snapshot = useSyncExternalStore(subscribe, getSnapshot);

Try it

A tiny store

Both displays stay in sync because they read the same snapshot from the same store.

An immutable snapshot of a list

Syntax

JSX
const snapshot = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot?);
TypeScript
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 getSnapshot or cache them. Returning { a: store.a } freshly each time is the classic bug.
  • Keep subscribe stable. If you define it inline in the component, React unsubscribes and resubscribes on every render. Define it at module level or wrap it in useCallback.
  • Selecting a piece: return a primitive (state.count) from getSnapshot to 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/offline or matchMedia change events as subscribe, and read navigator.onLine or mql.matches in getSnapshot; provide a server snapshot for SSR.
  • Prefer state or context for data that React already owns; this hook is for sources outside React.