useSyncExternalStore First Look

useSyncExternalStore is one of the hooks introduced in React 18. Initially I assumed it was reserved for use in libraries. It was advertised as a “library hook”, along with useInsertionEffect.

The following Hooks are provided for library authors to integrate libraries deeply into the React model, and are not typically used in application code.

And the changelog entry for it is similarly library-focused.

Add useSyncExternalStore to help external store libraries integrate with React

I don’t write libraries so I didn’t pay it any mind until I saw this tweet.

That got me curious, so I finally read the docs page and found there was a “Subscribing to a browser API” section in it all along. Better to discover it late than never I suppose. It starts off with this insight:

Another reason to add useSyncExternalStore is when you want to subscribe to some value exposed by the browser that changes over time.

Of course! I failed to realize that ‘external store’ doesn’t just mean ‘3rd party libraries’. The host environment — or more plainly, the browser — is an external store of state, state that we may want to consume in our React app. useSyncExternalStore can help us with that.

The million dollar question! Why do we bother? Why not stick to what we know? What’s wrong with the trusty useState & useEffect combo to read browser state?

The docs briefly mentions it but doesn’t really explain why:

[A browser API value] can change over time without React’s knowledge, so you need to read it with useSyncExternalStore

It has got to do with React 18’s most notable new feature, or behind-the-scenes mechanism as the React team like to think of it, concurrent rendering.

With concurrent rendering, React maintains multiple versions of a UI simultaneously (concurrently), one visible and one work-in-progress. This allows the browser to handle events while rendering instead of being blocked, making the app feel more responsive.

React can do this with its built-in state APIs — useState and useReducer — but not for state that lives outside React, because only a single version of external state can be accessed at a time ².

A consequence of this is that values in the external state used in render can change over time without React’s knowledge. This is the edge case that can cause the UI to tear; show two different values for the same data at the same time ³.

useSyncExternalStore is meant to mitigate that. It detects changes in external state during rendering and re-starts rendering before showing the inconsistent UI to the user ⁴. Because these updates are forced to be synchronous, React can guarantee that the UI will always be consistent ² ⁴ ⁵.

So in brief, useSyncExternalStore helps to avoid inconsistency and staleness in your UI when dealing with subscriptions.

Next to that, it has some additional benefits like support for server-rendering, and it’s arguably easier to use.

I’m always big on examples and use cases, how might useSyncExternalStore be used in apps? I tried my hand at rewriting two browser-syncing hooks I regularly use to make use of this new hook.

useMediaQuery is a hook to monitor media queries — yes the CSS ones — in JS-land, for example to grab user preferences like prefers-color-scheme.

[R]eading from a stateful DOM API requires setting up a subscription. This isn't even specific to React; that's how other frameworks work, too. So one definition of a "mutable source" [external store] is anything that requires a subscription to notify React of changes. For example, a canonical example is a useMediaQuery hook that subscribes to a MediaQueryList change event.

Here’s what I came up with


function getSnapshot(query: string) {
  return window.matchMedia(query).matches;
}
function subscribe(onChange: () => void, query: string) {
  const mql = window.matchMedia(query);
  mql.addEventListener("change", onChange);
  return () => {
    mql.removeEventListener("change", onChange);
  };
}
export function useMediaQuery(query: string) {  
  const subscribeMediaQuery = React.useCallback(
    (onChange: () => void) => subscribe(onChange, query),
    [query]
  );
  const matches = React.useSyncExternalStore(
    subscribeMediaQuery, 
    () => getSnapshot(query),
  );
  return matches;
}

Or view it on CodeSandbox.

Note that because query is used in subscribeMediaQuery, this function has to live inside useMediaQuery, making the function reference change with each call.

React will resubscribe every time you pass a different subscribe function between re-renders ⁶, which may lead to performance issues.

To only resubscribe when query changes, you need to wrap subscribeMediaQuery in useCallback and put query in its dependency array.

The subscribe function must also return its cleanup (unsubscribe) function — React calls it both when the component unmounts and right before resubscribing when query changes ⁷. That’s why subscribeMediaQuery returns the result of subscribe directly. If it didn’t, the old MediaQueryList’s change listener would never be torn down on a query change.

useMediaQuery isn’t only for layout breakpoints. One of my favorite uses is honoring the prefers-reduced-motion media query. Large motion on screen can cause dizziness, nausea or worse for some people, so their operating system lets them ask for reduced motion — and we ought to respect that. Josh Comeau makes the case far better than I can in Accessible Animations in React.

Because useMediaQuery already does the hard part, the whole thing is a one-liner:


function usePrefersReducedMotion() {
  return useMediaQuery("(prefers-reduced-motion: reduce)");
}

Then any component can tone down, or drop entirely, its animations:


function Card() {
  const prefersReducedMotion = usePrefersReducedMotion();
  return (
    <article className={prefersReducedMotion ? "card" : "card card--animated"}>
      …
    </article>
  );
}

Another common browser-syncing hook with a self-explanatory name. Here’s my stab at it.


function onWindowSizeChange(onChange: () => void) {
  window.addEventListener("resize", onChange);
  return () => window.removeEventListener("resize", onChange);
}
function getWindowWidthSnapshot() {
  return window.innerWidth;
}
function getWindowHeightSnapshot() {
  return window.innerHeight;
}
function useWindowSize() {
  const windowWidth = useSyncExternalStore(
    onWindowSizeChange,
    getWindowWidthSnapshot
  );
  const windowHeight = useSyncExternalStore(
    onWindowSizeChange,
    getWindowHeightSnapshot
  );
  return { width: windowWidth, height: windowHeight }; 
}

At first I tried returning the object directly from a single useSyncExternalStore like this:


function getWindowSizeSnapshot() {
  // 💥
  return {
    width: window.innerWidth,
    height: window.innerHeight
  }; 
}

And it blew up with a “too many rerenders” error. I had missed a very important caveat!

The value returned by getSnapshot must be immutable ⁸. That means no returning array or object literals in it!

I could fix it either by adding memoization or separating the height and the width into different useSyncExternalStore’s. Separating feels simpler so I opted for that.

This seems like a common-enough pitfall that it’d be nice to have an ESLint rule for, though I think it might be hard to write. Which reminds me I should really learn how to write ESLint rules, I have a list of ideas.

Avoiding Rerenders With a Selector Function

Sébastian wrote a great post on this hook, useSyncExternalStore - The underrated React API, he argues it’s an underutilized hook. One of the main benefits is that it easily supports selector functions.

A selector function reads the state as an argument, and returns data based on that state ⁹. By passing a selector function to getSnapshot, the number of updates can be limited.

Let’s apply the same optimization here. Maybe you don’t need to know the window size down to the pixel. This hook will trigger a render for each pixel anyway, it is over-returning. Say you only care about every 100px of change in width:


const widthStep = 100; // px
const widthSelector = (w: number) => (w ? Math.floor(w / widthStep) * widthStep : 1)
function windowWidthSnapshot(selector = (w: number) => w) {
  return selector(window.innerWidth);
}
function App() {
  const width = useSyncExternalStore(onWindowSizeChange, () =>
    windowWidthSnapshot(widthSelector)
  );
  ...
}

View the live code on CodeSandbox.

useSyncExternalStore’s secret superpower is its third, optional argument getServerSnapshot. It’s a function that returns the initial snapshot used only during server rendering and during hydration ¹⁰, so you can avoid rehydration perils.

There are two things to look out for with getServerSnapshot.

It must be defined if useSyncExternalStore is used on the server, an error will be thrown if it isn’t ¹⁰.
Its output must be the same on the client as it is on the server ¹¹.

What about SSR for the browser-state reading hooks like the ones shown above? It simply won’t work, information on window is only available on the client ¹². There’s no way to provide an initial value without it being a ¹³.

Using window.matchMedia in rendering logic is specifically mentioned as one of the most common causes of hydration errors ¹⁴.

So now what?

The React docs recommends to simply not render such components on the server ¹³.

[getServerSnapshot] lets you provide the initial snapshot value which will be used before the app becomes interactive.
If there is no meaningful initial value for the server rendering, you can force the component to render only on the client.

Which is something that never occurred to me. The new docs really keep on giving! I highly suggest you read that linked section. I’ll put a summary here for completeness and your convenience.

Convenient Summary

If a component throws an error on the server, React will not abort the server render. Instead, it will find the closest <Suspense> component above it and include its fallback (such as a spinner) into the generated server HTML.
On the client, React will attempt to render the same component again. If it does not error on the client, React will not display the error.
You can use this to opt out components from rendering on the server. To do this, throw an error from them in the server environment and then wrap them in a <Suspense> boundary to replace their HTML with fallbacks:

And in my own words: There’s no point in server-rendering a component that requires client-only info. Instead, leave a hole in the component tree on the server by throwing an error, then pass it to the client and let it fill the hole.

Questionable Advice

Well you asked for it. Here’s the dodgy option, it’s the “let’s try and hope for the best” approach.

React provides an escape hatch to suppress unavoidable hydration mismatches with the suppressHydrationWarning prop for elements ¹⁶. It only works for attributes and text content.

Mismatches should be viewed as a bug and React does not guarantee it will patch up the values correctly ¹⁷, use it at your own discretion. Also, if the user has disabled JavaScript, there’s no possibility for React to correct the values.

I tried it for the useWindowSize hook and it appeared to be fine.


function Canvas() {
  const windowWidth = useSyncExternalStore(
    onWindowSizeChange,
    () => window.innerWidth,
    () => 1200 // ⚠️ Fudge alert!
  );
  return <canvas width={windowWidth} suppressHydrationWarning />
}

I hope that demystifies the “what” and “why” of useSyncExternalStore a bit.

useSyncExternalStore is mostly but not only for libraries.
- It’s for subscribing to external state but in a broader sense than I thought.
- The browser is an external store that you may want to sync with in your React app
- It’s concurrent-safe so visual inconsistencies in UI are avoided.
If the subscribe function parameter is not stable React will resubscribe to the store every render.
The getSnapshot function parameter must return immutable values.
Its optional third function parameter getServerSnapshot is to support SSR
- It must return the same exact data on the initial client render as on the server, meaning you can’t read browser API’s on the server.
- If you can’t provide an initial value on the server, make the component client-only by throwing an error on the server and wrapping it in a <Suspense> boundary to display a fallback.