More Than You Need to Know About ReactDOM.flushSync

An in-depth look at what ReactDOM.flushSync does and what it’s good for.

Published 22-12-2023 · Last updated 12-5-2024

flushSync is part of what I like to call “Rare React”; the curious & uncommon parts, the outer circle of the API, the rarely needed . That just so happens to be a thing that I enjoy diving into and writing a blog post about.

So what does ReactDOM.flushSync do and when is it useful?

The names suggest it flushes synchronously. But what is flushing, what is being flushed, and when should that happen synchronously? What is all that good for?

Let us turn to the docs first

flushSync lets you force React to flush any updates inside the provided callback synchronously

and

Call flushSync to force React to flush any pending work and update the DOM synchronously.

Okay, so now we know that it flushes state updates synchronously to the DOM. But what does synchronously mean here exactly? Why are state updates called pending work? And what does flushing even mean?

To answer these questions and to know what problem flushSync solves, we first need to know what React does on state updates.

What Does React Do On Updates?

function Demo() {
  const [count, setCount] = useState(0);
  const [flag, setFlag] = useState(false);

  function handleClick() {
    setCount((c) => c + 1);
    setFlag((f) => !f);
  }

  return (
    <div>
     <button onClick={handleClick}>Next</button>
      <h1 style={{ color: flag ? "blue" : "black" }}>
        {count}
      </h1>
    </div>
  );
}

Update Queue

This React event handler contains two state updates.

¹ ² ³ ⁴ ⁵

The Waiter Analogy for Updates

The React team often uses the following analogy to explain batching:

Updating your component’s state automatically queues a render. You can imagine these as a restaurant guest ordering tea, dessert, and all sorts of things after putting in their first order, depending on the state of their thirst or hunger.

[Batching] is great for performance because it avoids unnecessary re-renders. It also prevents your component from rendering “half-finished” states where only one state variable was updated, which may cause bugs. This might remind you of how a restaurant waiter doesn’t run to the kitchen when you choose the first dish, but waits for you to finish your order.

flushSync is like telling the waiter to run the kitchen right away with this specific order. Just like the waiter running to the kitchen for every individual order isn’t efficient (not to say rude), forcing every update to be applied immediately isn’t efficient.

The Other Sync Update: useSyncExternalStore

useSyncExternalStore is another de-opt that forces updates to be synchronous, it’s meant the keep the UI in sync with the state of external stores; third-party libraries or browser API’s.

Check out useSyncExternalStore First Look and Concurrent React, External Stores, and Tearing

Time to answer the grand question: When is it useful?

Some browser APIs expect results inside of callbacks to be written to the DOM synchronously, by the end of the callback, so the browser can do something with the rendered DOM. In most cases, React handles this for you automatically. But in some cases it may be necessary to force a synchronous update.

Concretely, flushSync is for when you need to work around some issue where React updates the UI later than you need it to ⁸, requiring you to override batching.

Code thats depends on reading something from the DOM immediately after a state change
- Measuring a DOM Node
Perform DOM side-effects immediately after a state change
- Update the DOM in an onbeforeprint listener
- Scrolling to an element immediately after a state update
- Focus an element immediately after a certain state update

Usually, batching is safe, but some code may depend on reading something from the DOM immediately after a state change. For those use cases, you can use ReactDOM.flushSync() to opt out of batching.

Ryan Florence, of Remix & React Router, recently tweeted about using using flushSync for what he calls transactional effects. This doesn’t seem like a common term, I also think it sounds arcane so I’m hesitant to use it myself.

Anyhow, it’s when you 1) update a state and 2) immediately call a DOM method (like .focus()) or set a property (.scroll) on an element ref, and only for certain events that update that state.

You could do this with use(Layout)Effect but that gets awkward because you only want to do perform the side effect for certain events in which that state is updated, not whenever the state is updated.

A little later he posted a video explaining it in more detail using a good, real-world example. I’ve quoted the essence of it here but it’s worth a watch.

useEffect and useLayoutEffect run immediately after [a component] mounts. This is the crux of the problem with focus management using useEffect and useLayoutEffect. They are synchronisation mechanisms.
React takes your state and synchronises it to the DOM. use(Layout)Effect takes your state and then you get to synchronise it somewhere else, maybe localStorage, wherever. […]
Focus is not — for me — a synchronisation task. It is a transactional effect, not a synchronisation effect. There are only specific transactions where I want to actually focus this [input element].
[...]
[With flushSync], I get to think: what happens in this event?

The code shown in the video can be viewed here: Trellix app/routes/board.$id/components.tsx.

Synchronisation effect: Do something when the component is added and when this state is updated
Transactional effect: After this particular state update in this particular action, do something immediately

Class Component this.setState Callback

this.setState in class components supports an optional callback that React will call after the update is commited ⁹. While class components still work, no-one writes them anymore. The post-update callback wasn’t carried over to the useState hook, so we’ve lost this functionality (kind of).

flushSync is similar in that it also lets you ‘do something’ (perform a side effect) right after a state update is commited, just in a different way.

this.setState callback


<button
  onClick={() => {
    this.setState({ edit: true }, () => {
      ref.current.scrollTop = ref.current.scrollHeight;
    });
  }}
>

flushSync


<button
  onClick={() => {
    flushSync(() => {
      setEdit(true);
    });
    ref.current.scrollTop = ref.current.scrollHeight 
  }}
>

this.setState callback

flushSync


<button
  onClick={() => {
    this.setState({ edit: true }, () => {
      ref.current.scrollTop = ref.current.scrollHeight;
    });
  }}
>

Remix and React-Router (which Remix is built upon) recently introduced an option to do updates with flushSync to force internal react-router state updates to be synchronous. This is because react-router internal state updates are wrapped in startTransition to make them low-priority.

unstable_flushSync API
We've added a new unstable_flushSync option to the imperative APIs (useSubmit, useNavigate, fetcher.submit, fetcher.load) to let users opt-into synchronous DOM updates for pending/optimistic UI.

I must admit I haven’t played around with View Transitions yet but apparently flushSync is the way to make them work in React.

The key here is flushSync, which applies a set of state changes synchronously. Yes, there's a big warning about using that API, but Dan Abramov assures me it’s appropriate in this case. As usual with React and async code, when using the various promises returned by startViewTransition, take care that your code is running with the correct state.

Batching is a behind-the-scenes mechanism of React where it groups multiple state updates into a single re-render for better performance.
- In this way, updates are async; they are not applied right away.
Flushing is when React applies changes that result from state updates.
flushSync opts out of batching, it forces a particular state update to be applied (flushed) right away (synchronously).
- This is useful when React updates the UI later than you need it to, for example for managing focus and scroll positions after a state update.

There you have it, you now know more than you need to know about an obscure de-opt function of React. Remember that usually React does a fine job of scheduling updates, you need a good reason to override it.