useSyncExternalStore API and Parameters

useSyncExternalStore takes up to three arguments: subscribe, getSnapshot, and an optional getServerSnapshot. Together they tell React how to listen for changes and how to read the current value.

Understanding each argument is essential, since small mistakes in them are the most common source of bugs when using this hook.

subscribe receives a callback from React and must register it with the store so the callback runs whenever the store changes. It must return an unsubscribe function that React calls on cleanup.

React uses this to know when to re-read the snapshot, so subscribe is purely about wiring up and tearing down the change notification.

getSnapshot returns the current value of the store. React calls it during render to read state and again after notifications to detect whether the value changed.

Crucially, it must return a referentially stable result when the underlying data has not changed, returning the same reference rather than a fresh object each time.

The optional getServerSnapshot provides the value used during server-side rendering and the initial hydration pass. It exists because the browser-only getSnapshot may rely on APIs that do not exist on the server.

Providing it prevents hydration mismatches by giving the server a sensible value to render that matches what the client will produce initially.

The hook returns the current snapshot value, which you use directly in your component like any other piece of state. When the store changes, React re-renders and the hook returns the updated snapshot.

From the component perspective it feels like reading reactive state, even though the source of truth lives entirely outside React.

getSnapshot must run synchronously and return a value derived purely from the current store state. It should not perform async work or produce different results for the same underlying data.

React relies on calling it repeatedly and comparing results, so any non-determinism or side effects inside it can cause incorrect behavior.

Stores that hold immutable state make getSnapshot easy, since the current state object reference changes only when the data changes. Returning that reference gives stable comparisons for free.

This is why immutable update patterns pair so well with the hook: equal data means an equal reference, and React skips needless re-renders.

A frequent error is returning a brand new object or array from getSnapshot on every call, for example mapping or filtering inside it. React sees a new reference each time and thinks the value changed.

That triggers endless re-renders or warnings. The fix is to cache the derived value and return the same reference until the source data actually changes.

To avoid the loop, compute derived data outside getSnapshot or memoize it so the function returns a cached reference. The selector-style pattern many libraries use exists precisely to manage this stability.

The guiding rule is that two calls to getSnapshot with unchanged store data must return the exact same reference.

In practice you write a subscribe that adds and removes a listener, a getSnapshot that reads a stable current value, and, for SSR, a getServerSnapshot returning a server-safe value.

With those three correct, the hook delivers consistent, concurrent-safe reads of your external store with minimal ceremony.

Identify the role of getSnapshot.

The hook takes subscribe, getSnapshot, and optionally getServerSnapshot. subscribe wires a listener and returns an unsubscribe; getSnapshot reads the current value synchronously and must be referentially stable; getServerSnapshot supplies an SSR-safe value.

The classic pitfall is returning a new object every call, which causes infinite loops. Cache derived values so unchanged data yields the same reference.