Suggest an edit

Improve this article

Refine the answer for “What is useSyncExternalStore in React?”. Your changes go to moderation before they’re published.

Approval required

Content

What you’re changing

Title (EN)

Short answer (EN)

Shown above the full answer for quick recall.

Answer (EN)

**`useSyncExternalStore`** is a React 18 hook that lets components subscribe to external data sources while guaranteeing the same snapshot value across all reads in a single render pass, preventing tearing during concurrent rendering.

## Theory

### TL;DR

- Think of it as a **shared whiteboard**: every component in a render sees the exact same value, never a mix of old and new data
- The problem it solves: concurrent React can pause and resume mid-render, so a plain `navigator.onLine` read might return different values at different points in the same render
- Three arguments: `subscribe` (register a listener), `getSnapshot` (read the current value), `getServerSnapshot` (optional, for SSR)
- Use for browser APIs, third-party stores, and globals outside React. Skip for `useState`/`useReducer` - React already handles those without tearing

### Quick example

```tsx
function useOnlineStatus() {
  return useSyncExternalStore(
    // subscribe: attach listener, return cleanup
    (cb) => {
      window.addEventListener("online", cb);
      window.addEventListener("offline", cb);
      return () => {
        window.removeEventListener("online", cb);
        window.removeEventListener("offline", cb);
      };
    },
    () => navigator.onLine, // getSnapshot: pure read
    () => true              // getServerSnapshot: SSR default
  );
}
```

React calls `getSnapshot` once per render and reuses that value for the entire tree. No mutation happening mid-render can change what a component sees.

### What tearing actually is

Concurrent React splits work into units of varying priority. While processing a large component tree, the scheduler can pause, let higher-priority work run, then resume. If code reads `navigator.onLine` directly, one part of the tree might read `true` (before the network change) and another reads `false` (after the change) in the same commit. The UI shows both states at once. That is tearing.

`useSyncExternalStore` fixes this by locking in one atomic value from `getSnapshot` for the entire render pass.

### When to use it

- Browser API changes (online/offline status, media queries, `window.innerWidth`) - use `useSyncExternalStore`
- Third-party stores without built-in React bindings (Zustand internals, Redux DevTools) - use `useSyncExternalStore`
- Any mutable value that lives outside React and can change without React knowing - use `useSyncExternalStore`
- Plain React state (`useState`, `useReducer`) - skip this hook, React already handles those without tearing

### How it works internally

React calls `getSnapshot()` once per render pass and caches the result per component. All children reading from the same source get that cached value. When the `subscribe` callback fires, React schedules a re-render via its scheduler. The callback reference stays stable across renders, so subscriptions do not accumulate. On the server, `getServerSnapshot` runs instead of `getSnapshot` because `window` is not available there.

One thing I noticed in production apps: the most common footgun is returning a new object inside `getSnapshot`. React compares snapshots by reference, so returning `{ count: store.count }` on every call triggers infinite re-renders. Return primitives or stable references.

### Common mistakes

**Returning a new object in `getSnapshot`**

```tsx
// Wrong: new object on every call = infinite re-renders
const getSnapshot = () => ({ count: externalStore.count });

// Right: return a primitive
const getSnapshot = () => externalStore.count;
```

React calls `getSnapshot` multiple times and checks if the result changed. Different reference equals re-render. Always return primitives or memoize object snapshots.

**Mutating state inside `getSnapshot`**

```tsx
// Wrong: side effect inside snapshot read
const snap = () => { externalStore.value++; return externalStore.value; };

// Right: pure read only
const snap = () => externalStore.value;
```

`getSnapshot` must be a pure function. Side effects here cause infinite update loops.

**Missing cleanup in `subscribe`**

```tsx
// Wrong: listener never removed
(cb) => { window.addEventListener("resize", cb); }

// Right: return the cleanup function
(cb) => {
  window.addEventListener("resize", cb);
  return () => window.removeEventListener("resize", cb);
}
```

Without cleanup, each re-render stacks another listener. Memory leak, plus callbacks fire multiple times per event.

**Skipping `getServerSnapshot`**

```tsx
// Wrong: crashes on server where window is undefined
useSyncExternalStore(subscribe, () => window.innerWidth);

// Right: provide a server-safe default
useSyncExternalStore(subscribe, () => window.innerWidth, () => 1024);
```

Omitting the third argument causes hydration mismatch errors. The server renders with no value, the client hydrates with a real one, React warns or throws.

**Using it for plain React state**

If your data lives in `useState` or `useReducer`, this hook adds nothing. React already manages those without tearing. `useSyncExternalStore` is only for data that lives outside React's control.

### Real-world usage

- Zustand (v4+): uses `useSyncExternalStore` internally for all store subscriptions
- Redux Toolkit: powers DevTools time-travel snapshots
- TanStack Query: tracks `window` focus and blur for background refetch logic
- Framer Motion: reads pointer and gesture APIs from the browser
- Any production responsive hook (media queries, viewport dimensions) that needs to avoid layout shifts

### Follow-up questions

**Q:** What is tearing and why does it only matter in concurrent React?
**A:** Tearing is when two parts of the same render read an external value at different moments and get different results, producing an inconsistent UI. In synchronous React, renders are uninterruptible, so this cannot happen. Concurrent React pauses and resumes work, which makes it possible.

**Q:** How is this different from `useEffect` + `useState`?
**A:** The `useEffect` approach lags by one render. You subscribe in an effect, set state, then re-render. With `useSyncExternalStore`, the read is synchronous and tied to the render itself. No stale render, no intermediate flash.

**Q:** What happens on SSR if you skip `getServerSnapshot`?
**A:** React throws in development and produces a hydration mismatch in production. Always pass a server-safe default that does not rely on browser APIs.

**Q:** Why must `getSnapshot` return a consistent value between calls if nothing changed?
**A:** React calls `getSnapshot` multiple times during concurrent work to check for mid-render mutations. If it returns different values on repeated calls without the store actually changing, React logs a warning and may force a synchronous re-render.

**Q (senior):** How does `useSyncExternalStore` interact with `startTransition`?
**A:** `startTransition` marks state updates as low priority, deferring them. External store updates wrapped with `useSyncExternalStore` are treated as synchronous by React's scheduler. If a store change fires during a transition, React flushes it synchronously to prevent tearing, even if that interrupts the ongoing transition work.

## Examples

### Tracking online status

```tsx
function useOnlineStatus() {
  return useSyncExternalStore(
    (cb) => {
      window.addEventListener("online", cb);
      window.addEventListener("offline", cb);
      return () => {
        window.removeEventListener("online", cb);
        window.removeEventListener("offline", cb);
      };
    },
    () => navigator.onLine,
    () => true // server: assume online
  );
}

function NetworkBanner() {
  const isOnline = useOnlineStatus();
  if (isOnline) return null;
  return <div className="banner">You are offline</div>;
}
```

`getSnapshot` is a pure read of `navigator.onLine`. The same value is returned for the entire render pass, regardless of when the network event actually fires.

### Responsive layout with media query

```tsx
function useIsMobile() {
  return useSyncExternalStore(
    (cb) => {
      const mql = window.matchMedia("(max-width: 768px)");
      mql.addEventListener("change", cb);
      return () => mql.removeEventListener("change", cb);
    },
    () => window.matchMedia("(max-width: 768px)").matches,
    () => false // SSR: assume desktop
  );
}

function Sidebar() {
  const isMobile = useIsMobile();
  return (
    <nav className={isMobile ? "sidebar-mobile" : "sidebar-desktop"}>
      {/* consistent layout, no flash on resize */}
    </nav>
  );
}
```

The SSR default of `false` avoids hydration mismatches on desktop-first layouts. Without `getServerSnapshot`, the server and client render different class names and React throws a warning.

### External store integration (how Zustand works under the hood)

```tsx
const counterStore = {
  count: 0,
  listeners: new Set<() => void>(),
  increment() {
    this.count++;
    this.listeners.forEach((l) => l());
  },
  subscribe(cb: () => void) {
    this.listeners.add(cb);
    return () => this.listeners.delete(cb);
  },
  getSnapshot() {
    return this.count;
  },
};

function Counter() {
  const count = useSyncExternalStore(
    counterStore.subscribe.bind(counterStore),
    counterStore.getSnapshot.bind(counterStore),
    () => 0
  );
  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => counterStore.increment()}>+1</button>
    </div>
  );
}
```

The store mutates directly outside React, but `useSyncExternalStore` bridges it into the render cycle. Each `increment` call notifies all listeners, React schedules a re-render, and `getSnapshot` returns the new count. This is roughly how Zustand v4 implements its React bindings.

Markdown · drag & drop images · ⌘B / ⌘I shortcuts1295 words

For the reviewer

Note to the moderator (optional)

Visible only to the moderator. Helps review go faster.