Most React state management confusion stems from teams treating external stores as if they're native React state. The assumption breaks in React 18's concurrent rendering model, where a component can read from a store twice during a single render and receive different values. This inconsistency—called tearing—corrupts UI state in ways that are expensive to debug and embarrassing to ship. The pattern that eliminates tearing is `useSyncExternalStore`, the hook that every production state library now uses under the hood. Developers dismiss it as "library internals" without realizing it's the foundation that makes Zustand, Jotai, and Redux work correctly in concurrent mode. When you understand this hook, you understand why your state library behaves the way it does—and when you need to build a custom store, you know exactly how to integrate it safely. ```mermaid flowchart LR A("Component reads store") --> B("Concurrent render interrupts") B --> C("Component re-reads store") C --> D("store value changed between reads") D --> E("UI renders with mixed old and new state") style D stroke:#fbbf24,fill:#3a2f0b,color:#fef3c7 style E stroke:#ef4444,fill:#450a0a,color:#fca5a5 ``` React 18 introduced time-slicing and transitions that allow renders to pause and resume. A store outside React's control can change during that pause. Without `useSyncExternalStore`, the resumed render sees new data while sibling components still reference old snapshots. The UI enters an inconsistent state where a product list shows five items but the cart count displays four. ```mermaid flowchart LR A("Component reads store") --> B("useSyncExternalStore subscribes") B --> C("Store changes trigger synchronous re-render") C --> D("All components read same snapshot") D --> E("UI stays consistent across concurrent boundaries") style C stroke:#c084fc,fill:#3b0764,color:#f3e8ff,stroke-width:4px style E stroke:#34d399,fill:#0b3b2e,color:#d1fae5 ``` `useSyncExternalStore` solves this by forcing React to commit any in-progress render when the external store changes. The guarantee is simple: every component in a render tree sees the same snapshot value, even when renders interleave or suspend. This synchronization is what "sync" means in the hook's name—it's not about synchronous code execution, it's about snapshot consistency. ## Key Takeaways - `useSyncExternalStore` prevents tearing by ensuring all components in a concurrent render read the same snapshot value from an external store. - The hook requires three pieces: a stable `subscribe` function that registers a listener, a `getSnapshot` function that returns immutable data, and optionally a `getServerSnapshot` for SSR hydration. - Every major state library (Zustand, Jotai, Redux Toolkit) now uses `useSyncExternalStore` internally—understanding it reveals why their APIs enforce certain patterns like immutable updates. - Building a custom store with this hook takes fewer than 50 lines but demands strict adherence to immutability and subscription stability to avoid infinite loops. - Choose `useSyncExternalStore` for any data source outside React's control (browser APIs, WebSockets, shared workers); use Context for component-tree-scoped state that doesn't need external sync. ## The Hook Signature: subscribe, getSnapshot, and getServerSnapshot `useSyncExternalStore` accepts three arguments, and their interaction determines whether the integration succeeds or fails. The first argument is `subscribe`, a function that takes a callback and registers it with the external store. When the store changes, it must invoke all registered callbacks. The second argument is `getSnapshot`, which returns the current store value. React calls this function during render and compares the returned reference to detect changes. The optional third argument is `getServerSnapshot`, which provides the initial value during server-side rendering when the external store doesn't exist yet. ```mermaid flowchart TD A("useSyncExternalStore called") --> B("React invokes subscribe with callback") B --> C("subscribe registers callback with store") C --> D("Store changes") D --> E("Store invokes all registered callbacks") E --> F("React calls getSnapshot") F --> G("React compares new snapshot to previous") G --> H{"Reference changed?"} H -->|Yes| I("React schedules synchronous re-render") H -->|No| J("No re-render") I --> K("All components read consistent snapshot") style F stroke:#c084fc,fill:#3b0764,color:#f3e8ff,stroke-width:4px style I stroke:#34d399,fill:#0b3b2e,color:#d1fae5 ``` The contract between these functions is rigid. The `subscribe` function must return an unsubscribe function that removes the callback when the component unmounts. React expects this cleanup to prevent memory leaks when components re-render or unmount. The failure mode here is subtle: if `subscribe` returns `undefined` or a non-function, React silently skips cleanup and the callback continues firing after the component is gone, updating state that no longer exists. The `getSnapshot` function must return the same reference for equal values. React uses `Object.is` comparison to determine if a re-render is necessary. Returning a new object on every call—even if the contents are identical—triggers infinite render loops. This is why store implementations typically cache snapshots and only create new references when the underlying data actually changes. The discipline required here is stricter than `useMemo` or `useCallback` because React cannot fix violations for you. The `getServerSnapshot` argument addresses the timing mismatch between server and client. On the server, external stores like `localStorage` or `WebSocket` connections don't exist. React needs a value to render the initial HTML. When the client hydrates, it must use the same initial value to match the server-rendered markup, then switch to the live store. Omitting `getServerSnapshot` when targeting SSR causes hydration mismatches that manifest as content flashes or suppressed event handlers. ## Building a Simple External Store: Browser Storage Example The clearest way to understand `useSyncExternalStore` is to build a custom hook that wraps browser storage. The requirement is simple: when `localStorage` changes in one tab, all subscribed components across all tabs must re-render with the new value. This cross-tab synchronization is exactly the kind of external data source that Context cannot handle and where custom event listeners fail without careful subscription management. ```typescript function createStorageStore(key: string, initialValue: T) { let currentValue = initialValue; const listeners = new Set<() => void>(); // Load initial value from localStorage if (typeof window !== 'undefined') { const stored = localStorage.getItem(key); if (stored !== null) { try { currentValue = JSON.parse(stored); } catch { // If parse fails, use initialValue } } } const subscribe = (callback: () => void) => { listeners.add(callback); // Listen to storage events from other tabs const handleStorage = (e: StorageEvent) => { if (e.key === key) { const newValue = e.newValue ? JSON.parse(e.newValue) : initialValue; currentValue = newValue; listeners.forEach(listener => listener()); } }; window.addEventListener('storage', handleStorage); return () => { listeners.delete(callback); window.removeEventListener('storage', handleStorage); }; }; const getSnapshot = () => currentValue; const getServerSnapshot = () => initialValue; const setState = (nextValue: T | ((prev: T) => T)) => { const newValue = typeof nextValue === 'function' ? (nextValue as (prev: T) => T)(currentValue) : nextValue; currentValue = newValue; localStorage.setItem(key, JSON.stringify(newValue)); listeners.forEach(listener => listener()); }; return { subscribe, getSnapshot, getServerSnapshot, setState }; } function useLocalStorage(key: string, initialValue: T) { const store = React.useMemo( () => createStorageStore(key, initialValue), [key] ); const value = React.useSyncExternalStore( store.subscribe, store.getSnapshot, store.getServerSnapshot ); return [value, store.setState] as const; } // Usage function ThemeToggle() { const [theme, setTheme] = useLocalStorage('theme', 'light'); return ( ); } ``` The implementation maintains a `listeners` Set to track subscribed components. When `setState` is called, it updates both the in-memory `currentValue` and `localStorage`, then notifies all listeners. This dual update is critical: updating only `localStorage` would miss components in the same tab, while updating only memory would miss cross-tab synchronization. The `storage` event listener handles changes from other tabs. Browser storage events only fire in tabs that did not trigger the change. When another tab calls `setTheme`, the event fires in this tab, updating `currentValue` and notifying local listeners. Without this listener, the hook would only work within a single tab—a common mistake when developers test in one browser window. The `useMemo` call ensures `createStorageStore` runs once per unique key. Without it, every render would create a new store instance with a new `subscribe` function, and React would treat that as a subscription change, triggering unsubscribe-then-resubscribe on every render. This creates a memory leak where old listeners accumulate because the cleanup function references a stale `listeners` Set. ## How Zustand, Jotai, and Redux Use useSyncExternalStore Under the Hood State libraries adopted `useSyncExternalStore` to eliminate tearing without forcing developers to understand the hook directly. The abstraction works because these libraries control the store implementation and can guarantee the subscription and snapshot contracts. When developers call `useStore` or `useAtom`, they're indirectly invoking `useSyncExternalStore` with library-managed functions. ```mermaid flowchart LR subgraph Zustand["Zustand store.subscribe"] A1("create((set) => state)") A2("Internal listeners Set") A3("useStore calls useSyncExternalStore") end subgraph Jotai["Jotai atom.subscribe"] B1("atom with read/write") B2("Atom value cache") B3("useAtom calls useSyncExternalStore") end subgraph Redux["Redux store.subscribe"] C1("configureStore with reducers") C2("Middleware pipeline") C3("useSelector calls useSyncExternalStore") end A3 --> D("Components read consistent snapshots") B3 --> D C3 --> D D --> E("Concurrent renders never tear") style D stroke:#c084fc,fill:#3b0764,color:#f3e8ff,stroke-width:4px style E stroke:#34d399,fill:#0b3b2e,color:#d1fae5 ``` Zustand exposes a `subscribe` method on the store object that accepts a listener function. Internally, it maintains a Set of listeners identical to the storage example above. When developers call `set` to update state, Zustand updates the internal store object, then invokes every listener. The `useStore` hook wraps this with `useSyncExternalStore`, passing the store's `subscribe` method directly and a `getSnapshot` function that returns the current state reference. Jotai takes a different approach because its atoms are independent units rather than a single store. Each atom has its own subscription mechanism, but the library maintains a global WeakMap that tracks which atoms are mounted and which components subscribe to each. When an atom's value changes, Jotai looks up all subscribed components in the WeakMap and notifies them. The `useAtom` hook calls `useSyncExternalStore` with an atom-specific subscribe function that registers the component in this WeakMap. Redux Toolkit's `useSelector` hook migrated from a custom subscription system to `useSyncExternalStore` in version 8. The store's `subscribe` method registers listeners that fire on every action dispatch. The `getSnapshot` function runs the selector against the current state and returns the result. Redux compares the selector output with `Object.is`, so selectors that return new objects on every call cause the same infinite loop problem. This is why Redux documentation emphasizes memoized selectors—it's a requirement of `useSyncExternalStore`, not a Redux-specific optimization. The common pattern across all three libraries is that they handle subscription stability and snapshot immutability internally, so developers never write a `subscribe` function by hand. This abstraction is valuable, but it also means teams adopt these libraries without understanding why certain patterns—like immutable updates in Zustand or memoized selectors in Redux—are mandatory rather than suggested. ## Implementing a Type-Safe Mini State Manager in 40 Lines Understanding the hook's mechanics makes building a custom store straightforward when the requirements don't fit existing libraries. The goal is a global store with actions, TypeScript safety, and automatic re-renders—essentially Zustand's core features in minimal code. ```typescript type Listener = () => void; type SetState = (partial: Partial | ((state: T) => Partial)) => void; interface StoreApi { getState: () => T; setState: SetState; subscribe: (listener: Listener) => () => void; } function createStore>( initialState: T ): StoreApi { let state = initialState; const listeners = new Set(); const getState = () => state; const setState: SetState = (partial) => { const nextState = typeof partial === 'function' ? partial(state) : partial; state = { ...state, ...nextState }; listeners.forEach(listener => listener()); }; const subscribe = (listener: Listener) => { listeners.add(listener); return () => listeners.delete(listener); }; return { getState, setState, subscribe }; } function createUseStore>( store: StoreApi ) { return function useStore(): T; return function useStore(selector: (state: T) => U): U; return function useStore(selector?: (state: T) => U) { const selectedState = React.useSyncExternalStore( store.subscribe, () => selector ? selector(store.getState()) : store.getState(), () => selector ? selector(store.getState()) : store.getState() ); return selectedState as U extends undefined ? T : U; }; } // Usage with actions interface CounterState { count: number; increment: () => void; decrement: () => void; reset: () => void; } const counterStore = createStore({ count: 0, increment: () => {}, decrement: () => {}, reset: () => {}, }); // Bind actions after store creation counterStore.setState({ increment: () => counterStore.setState(s => ({ count: s.count + 1 })), decrement: () => counterStore.setState(s => ({ count: s.count - 1 })), reset: () => counterStore.setState({ count: 0 }), }); const useCounter = createUseStore(counterStore); function Counter() { const { count, increment, decrement, reset } = useCounter(); return (

Count: {count}

); } ``` The `createStore` function establishes the core pattern: a closure that encapsulates state and listeners, exposing three methods that implement the `useSyncExternalStore` contract. The `setState` implementation merges partial updates with the current state using the spread operator, ensuring a new reference even when only one property changes. This reference change is what triggers React's comparison in `useSyncExternalStore`. The `createUseStore` wrapper adds TypeScript overloads that support both full state selection and custom selectors. The hook calls `useSyncExternalStore` with the store's subscribe method and a snapshot function that applies the selector. The selector runs on every call to `getSnapshot`, which happens during render and whenever the store changes. Expensive selectors here would hurt performance, but for most applications the cost is negligible compared to component render time. The action binding pattern addresses a common confusion with this architecture. Actions need access to `setState`, but `setState` is only available after `createStore` returns. The solution is to define action placeholders in the initial state, then bind the real implementations after store creation. This two-step initialization feels awkward at first but eliminates circular dependencies and keeps the store creation function pure. ## Common Mistakes: Snapshot Mutation, Unstable subscribe, and SSR Hydration The three failure modes that break `useSyncExternalStore` integrations all stem from violating the hook's contracts. These bugs are invisible in development and only surface in production when concurrent rendering or server hydration exposes the timing assumptions. ```mermaid flowchart LR A("Component mounts") --> B{"subscribe function stable?"} B -->|No| C("React unsubscribes and resubscribes on every render") C --> D("Old listeners accumulate") D --> E("Memory leak and duplicate updates") B -->|Yes| F{"getSnapshot returns same reference?"} F -->|No| G("React detects change on every call") G --> H("Infinite render loop") F -->|Yes| I{"getServerSnapshot provided for SSR?"} I -->|No| J("Hydration mismatch") J --> K("React suppresses event handlers") I -->|Yes| L("Store integrates safely") style C stroke:#fbbf24,fill:#3a2f0b,color:#fef3c7 style E stroke:#ef4444,fill:#450a0a,color:#fca5a5 style G stroke:#fbbf24,fill:#3a2f0b,color:#fef3c7 style H stroke:#ef4444,fill:#450a0a,color:#fca5a5 style J stroke:#fbbf24,fill:#3a2f0b,color:#fef3c7 style K stroke:#ef4444,fill:#450a0a,color:#fca5a5 style L stroke:#34d399,fill:#0b3b2e,color:#d1fae5 ``` Snapshot mutation happens when developers modify the returned object instead of creating a new reference. A store that maintains an array and calls `array.push()` violates immutability because the array reference stays the same. React's `Object.is` comparison sees no change, so components don't re-render even though the data changed. The fix is always to replace the array with a new one: `[...array, newItem]`. This requirement mirrors Redux's reducer rules and exists for the same reason—reference equality is the only performant way to detect changes. Unstable `subscribe` functions occur when the subscribe callback is defined inline without `useCallback` or when it closes over changing variables. React treats function identity changes as subscription changes and runs the cleanup logic. If cleanup doesn't properly remove the old listener, the Set or array of listeners grows without bound. The symptom is components re-rendering multiple times per state change—once per accumulated listener. The fix is to ensure `subscribe` is defined once at store creation time and returns a stable function reference. SSR hydration mismatches manifest when `getServerSnapshot` is omitted or returns a different value than the initial client-side call to `getSnapshot`. The server renders the component with one value, React hydrates with another, and the mismatch causes React to assume the HTML is invalid. In production mode with selective hydration, React silently suppresses event handlers on the mismatched nodes, leading to buttons that don't respond to clicks. The fix is to provide a `getServerSnapshot` that matches the server environment—often just returning the `initialValue` from store creation. ## When to Use useSyncExternalStore vs Context vs External Libraries The decision point for `useSyncExternalStore` is whether the data source lives outside React's render lifecycle. Browser APIs, WebSocket connections, third-party libraries with their own state—these are external stores that change independently of component renders. Context and `useState` are sufficient when state exists only within the component tree and React controls when it changes. ```mermaid flowchart LR A("State requirement") --> B{"Data source outside React?"} B -->|Yes| C{"Need to share across component trees?"} C -->|Yes| D("useSyncExternalStore with global store") C -->|No| E{"Need concurrent-safe subscriptions?"} E -->|Yes| D E -->|No| F("Custom hook with useState") B -->|No| G{"State scoped to one component?"} G -->|Yes| H("useState") G -->|No| I{"State scoped to subtree?"} I -->|Yes| J("Context with useMemo provider value") I -->|No| K("External library like Zustand") style D stroke:#c084fc,fill:#3b0764,color:#f3e8ff,stroke-width:4px style H stroke:#34d399,fill:#0b3b2e,color:#d1fae5 style J stroke:#34d399,fill:#0b3b2e,color:#d1fae5 style K stroke:#7c9cf0,fill:#142544,color:#eaf2ff ``` Context is the right choice for theme, locale, or authenticated user data that needs to flow down the tree but doesn't need to synchronize with external changes. The key consideration is whether the state could change while a component is suspended or rendering concurrently. If not—if state changes only happen through user actions that trigger synchronous React updates—Context handles it. The performance concern with Context isn't about the hook itself but about how often the provider value changes and re-renders consumers. External libraries like Zustand or Jotai become valuable when multiple parts of the application need to share state that isn't naturally parent-child related. A shopping cart that three different routes access is easier to model as a global store than to lift state to a shared ancestor and prop-drill through unrelated components. These libraries use `useSyncExternalStore` internally, so choosing them isn't avoiding the hook—it's choosing a battle-tested implementation instead of writing one from scratch. The line between "build your own" and "use a library" depends on complexity, not just features. A global store with two or three slices of state and a handful of actions fits comfortably in 50 lines of custom code. A store with async actions, persistence, devtools integration, and complex selector patterns justifies the dependency on a library. The cost of the library is maintenance and bundle size; the cost of custom code is testing and documentation. ## Frequently Asked Questions ### Why does my component re-render infinitely when using useSyncExternalStore? The most common cause is a `getSnapshot` function that returns a new object reference on every call, violating React's `Object.is` comparison. Ensure `getSnapshot` caches its result and only returns a new reference when the underlying data actually changes, typically by maintaining a mutable state variable that updates only on subscription callbacks. ### Can I use useSyncExternalStore with async data sources like fetch or WebSocket? Yes, but the `getSnapshot` function must always return a synchronous value representing the current state—"loading", "error", or the resolved data. The subscription logic handles async events (WebSocket messages, fetch completion) and updates the cached state, which `getSnapshot` then returns. Never make `getSnapshot` itself async or return a Promise. ### Do I need getServerSnapshot if my app doesn't use server-side rendering? No, the third argument is optional and only necessary when rendering on the server. For client-only apps, omit it entirely. React only calls `getServerSnapshot` during server rendering to generate initial HTML, so providing it for a client-only app has no effect but doesn't cause errors. ### How do I prevent memory leaks with useSyncExternalStore subscriptions? The `subscribe` function must return an unsubscribe callback that removes the listener from the store's internal Set or array. When React unmounts the component or the subscription changes, it calls this cleanup function. Forgetting to return a cleanup function or returning a non-function value prevents React from cleaning up, leaving stale listeners that continue firing after the component unmounts. ### Why do libraries like Zustand still recommend memoized selectors if useSyncExternalStore handles subscriptions? `useSyncExternalStore` prevents tearing but doesn't prevent unnecessary renders. A selector that returns a new object on every call (`state => ({ count: state.count })`) creates a new reference even when `count` hasn't changed, triggering re-renders. Memoization ensures the selector returns the same reference for equal values, which React's `Object.is` comparison then recognizes as unchanged, skipping the render. ## useSyncExternalStore in 2026: The Foundation of Modern React State The hook that developers dismissed as "advanced" or "library internals" is now unavoidable for anyone working with React 18+ in production. Understanding `useSyncExternalStore` is understanding why state libraries enforce immutability, why selectors need memoization, and why Context doesn't solve every sharing problem. These aren't arbitrary rules—they're consequences of the concurrent rendering model and the guarantees this hook provides. The practical impact is that teams building custom integrations—browser storage, WebSocket state, third-party SDK connections—now have a clear pattern instead of fragile workarounds. The days of "just use an event listener and useState" are over. That approach breaks subtly under concurrent rendering, and fixing it after the fact is expensive. Building on `useSyncExternalStore` from the start means the integration scales from prototype to production without rewrites. For library authors, this hook is non-negotiable. Any state management library that doesn't use `useSyncExternalStore` internally will tear under concurrent rendering, and users will report inconsistent UI states that are impossible to reproduce reliably. The migration from custom subscription systems to this hook is why Zustand, Jotai, and Redux all had major version bumps in the React 18 era. The API surface stayed similar, but the internal implementation had to change to guarantee safety. That covers the essential patterns for `useSyncExternalStore`. Apply these in production and the difference will be immediate—components that stay consistent under suspense, state that synchronizes across tabs, and integrations that don't break when React introduces new concurrent features. The hook isn't just about preventing bugs; it's about building state architecture that doesn't need defensive workarounds.

Posts tagged “useSyncExternalStore”

React useSyncExternalStore in 2026: The Hook Every State Library Uses and Why You Should Understand It