useSyncExternalStore

In one minute

Some state lives outside React: the browser’s online status, localStorage, a plain JavaScript store, a third-party library. useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot?) lets components read it and re-render when it changes:

• subscribe(onChange) connects to the store and returns an unsubscribe function.
• getSnapshot() returns the current value. When nothing changed, it must return the same value.
• getServerSnapshot() gives the value to use on the server and during hydration.

It’s safer than useEffect + useState, because React can check the store during rendering and never show two different versions at once (“tearing”). State libraries like Redux and Zustand are built on it.

You’ll be able to: subscribe to a browser API and to your own store, and avoid the two classic mistakes: an unstable snapshot and a missing server snapshot.

1let state = { count: 0 }2const listeners = new Set()3const cartStore = {4  getSnapshot: () => state,5  subscribe(listener) { listeners.add(listener); return () => listeners.delete(listener) },6  add() {7    state = { count: state.count + 1 } // new only when it changes8    listeners.forEach(l => l())9  },10}1112function useCartCount() {13  return useSyncExternalStore(cartStore.subscribe, cartStore.getSnapshot).count14}

1function useCartBad() {2  return useSyncExternalStore(3    cartStore.subscribe,4    () => ({ ...cartStore.getSnapshot() }), // a new copy every call5  )6}

The example

1. Online status

function subscribe(onChange: () => void) {
	window.addEventListener('online', onChange)
	window.addEventListener('offline', onChange)
	return () => {
		window.removeEventListener('online', onChange)
		window.removeEventListener('offline', onChange)
	}
}

function useOnlineStatus() {
	return useSyncExternalStore(
		subscribe,
		() => navigator.onLine, // on the client
		() => true, // on the server, and during hydration
	)
}

function CheckoutButton() {
	const online = useOnlineStatus()
	return <button disabled={!online}>{online ? 'Place order' : 'Offline: reconnect to order'}</button>
}

subscribe is defined outside the component, so it’s the same function every render, and React doesn’t resubscribe. Recorded while Chrome was switched offline and back:

{
  "logs": [],
  "warnings": [],
  "before": "Place order",
  "offline": {
    "text": "Offline: reconnect to order",
    "disabled": true
  },
  "back": "Place order"
}

2. A cart store shared by two React roots

Some pages have more than one React root: say, an older header and a new product page. They can’t share React state or context, but they can share a store.

type Cart = { count: number }

function createCartStore() {
	let state: Cart = { count: 0 }
	const listeners = new Set<() => void>()
	return {
		getSnapshot: () => state,
		subscribe(listener: () => void) {
			listeners.add(listener)
			return () => listeners.delete(listener)
		},
		add() {
			state = { count: state.count + 1 } // a new object only when something changed
			listeners.forEach((l) => l())
		},
	}
}

const cartStore = createCartStore()

function useCartCount() {
	return useSyncExternalStore(cartStore.subscribe, cartStore.getSnapshot).count
}

function HeaderBadge() {
	const count = useCartCount()
	log(`render HeaderBadge (${count})`)
	return <span id="badge">🛒 {count}</span>
}

function ProductPage() {
	const count = useCartCount()
	log(`render ProductPage (${count})`)
	return <button id="add" onClick={cartStore.add}>Add to cart ({count} so far)</button>
}

// Two separate React apps on one page, e.g. an older header and a new product page
function mountBoth(header: HTMLElement, page: HTMLElement) {
	createRoot(header).render(<HeaderBadge />)
	createRoot(page).render(<ProductPage />)
}

Clicking “Add to cart” in the product page:

render HeaderBadge (1)
render ProductPage (1)

Both roots re-rendered. The header badge now shows 🛒 1.

3. Mistake: a new snapshot on every call

function useCartBad() {
	return useSyncExternalStore(cartStore.subscribe, () => ({ ...cartStore.getSnapshot() }))
}

Recorded:

The result of getSnapshot should be cached to avoid an infinite loop

uncaught: Maximum update depth exceeded. This can happen when a component repeatedly calls setState inside componentWillUpdate or componentDidUpdate. React limits the number of nested updates to prevent infinite loops.

Every call returns a new object, so to React the store looks like it changes on every render, which schedules another render, and so on. The store above avoids this by creating a new state object only in add().

4. Mistake: no server snapshot

function useOnlineStatusClientOnly() {
	return useSyncExternalStore(subscribe, () => navigator.onLine)
}

Rendering both buttons with renderToString, as a server would:

log('with getServerSnapshot:', renderToString(<CheckoutButton />))
try {
	log('without:', renderToString(<ClientOnlyButton />))
} catch (e) {
	log('without: threw', (e as Error).message)
}

with getServerSnapshot: <button>Place order</button>
without: threw Missing getServerSnapshot, which is required for server-rendered content. Will revert to client rendering.

The server has no navigator.onLine. With getServerSnapshot, it renders “Place order”, and the client updates after hydration if the real value is different. Without it, server rendering fails, and React falls back to rendering that part on the client.

How it works

• Subscribe once, read on every render. React calls subscribe after mounting (and again only if you pass a different subscribe function). On every render it calls getSnapshot and compares the result with the last one using Object.is.
• Changes come from the store. When the store calls the listener, React calls getSnapshot again. If the snapshot changed, it re-renders that component. Updates from external stores are rendered synchronously, never as a background transition, so the screen can’t show a mix of old and new store values.
• The snapshot must be immutable and cached. Return the store’s own value, and replace it with a new object only when something changes. In development, React calls getSnapshot twice and warns if the results differ (recorded).
• Select small values. useCartCount() returns count, a number, so components re-render only when the number changes. For derived objects, memoize them in the store, or use a library’s selector API.

Common mistakes

• Building a new object or array in getSnapshot: () => ({ ...state }), () => items.filter(…). This causes an infinite loop (recorded).
• Defining subscribe inside the component without useCallback: React unsubscribes and resubscribes on every render.
• Leaving out getServerSnapshot in server-rendered apps (recorded error).
• Using it for state React could own. If the state is only used by your components, useState, useReducer or context is simpler.

Interview Q&A

Related

• Context with use: shared state inside React.
• Side Effects: why subscriptions need cleanup.
• Scheduler, Lanes and Batching: why store updates are rendered synchronously.

Sources

• react.dev: useSyncExternalStore, Subscribing to an external store
• The useSyncExternalStore working-group discussion: What is tearing?
• Topic order inspired by Kent C. Dodds’ EpicReact Advanced React APIs workshop; the example app and code here are this handbook’s own.

Primary source: react.dev/reference/react/useSyncExternalStore