Behavioral changes to Suspense in React 18

[acdlite]

Overview

We added basic support for Suspense in React 16.x. But it wasn’t full support for Suspense — it doesn’t do all the things we’ve shown off in our demos, like delayed transitions (i.e. waiting for the data to resolve before proceeding with a state transitions), or placeholder throttling (reducing UI thrash by throttling the appearance of nested, successive placeholders), or SuspenseList (coordinating the appearance of a list or grid of components, like by streaming them in order). We've been referring to the version of Suspense that exists in 16 and 17 as Legacy Suspense.

Our full suite of Suspense functionality depends on Concurrent React, which we are adding in React 18. That means Suspense works slightly differently in React 18 than in previous versions. Technically, this is a breaking change, but as with automatic update batching, we expect the impact on existing code to be relatively minimal, and that it won’t impose a significant migration burden on authors migrating their apps. (If this ends up not being the case during pre-release testing, we have a backup strategy that we can discuss in a separate thread.)

This post discusses the behavioral differences — the parts that affect the compatibility of user component code.

Note on terminology

The feature itself is still called just "Suspense".

The distinction between "Legacy Suspense" and "Concurrent Suspense" only matters in the context of migration. Since we expect most people to not have any significant hurdles upgrading, you won't see these terms outside of the migration discussion.

Siblings of a suspended component may be interrupted

Simplified explanation

In both Legacy Suspense and Concurrent Suspense, the basic user experience is the same. In the following example, until the data in ComponentThatSuspends resolves, React will display the Loading component in its place:

<Suspense fallback={<Loading />}>
  <ComponentThatSuspends />
  <Sibling />
</Suspense>

The difference is how a suspended components affects the rendering behavior of its siblings:

• In Legacy Suspense, the Sibling component is immediately mounted to the DOM and its effects/lifecycles are fired. Then we hide it.
  • 🟡 React 17 demo sandbox showing all the effects firing too early. (Notice the effect logs appear before logs like ===== fetched posts ===== .)
• In Concurrent Suspense, the Sibling component is not mounted to the DOM. Its effects/lifecycles are also NOT fired until ComponentThatSuspends resolves, too. This fixes some long-standing issues affecting component libraries.
  • ✅ React 18 with createRoot demo sandbox showing effects delayed until the content is ready. (Notice the effect logs appear after logs like ===== fetched posts ===== .)

Detailed explanation

In previous versions of React, there was an implied guarantee that a component that starts rendering will always finish rendering. For example, when rendering a class component, there's 1:1 correspondence between when the render method is called and when componentDidMount/Update is called. Most people don't really think about this guarantee, or intentionally rely on it, but it's possible to accidentally rely on it without realizing.

You can see how this is important in the context of a feature like Suspense, whose purpose to delay the rendering of a subtree until all the data in the tree has resolved. If one component in the tree isn't ready to commit yet, what do we do about its siblings, some of which may have already started rendering? (For example, if the third component in a list of items suspends, the render method of the first two items as already been called.)

When we first introduced Legacy Suspense, we found a way to maintain the 1:1 render-commit correspondence with a clever trick: we would skip over the suspended child, proceed rendering the siblings, and commit as much of the DOM tree as we can. This means the DOM is an inconsistent state, but we can get away with this because we're going to replace it with a fallback UI, anyway. Before the browser is allowed to paint, we show the fallback UI and hide everything inside the Suspense boundary with display: hidden.

With this trick, the sibling's rendering behavior is unaffected, but from the user's perspective they don't see any inconsistency: they just see a placeholder.

Legacy Suspense is a bit weird, but it was a good compromise solution for introducing the basic Suspense functionality in a backwards compatible way.

In Concurrent Suspense, what we do instead is interrupt the siblings and prevent them from committing. we wait to commit everything inside the Suspense boundary — the suspended component and all its siblings — until the suspended data has resolved. Then we commit the whole tree simultaneously in a single, consistent batch. This fits much better with the rest of our rendering a model, both in terms of implementation complexity and in terms of the the features we can build on top of this behavior. And it’s arguably a more predictable behavior from the developer’s perspective, once you adopt the constraint that side effects can’t be in render (which was already discouraged).

But it does require that your code is resilient to being interrupted. However, this is the same requirement that time slicing via startTransition introduces. Usually, the solution involves moving side effects and mutations from the render phase into the commit phase. You can use Strict Mode to surface these types of bugs during development.

[acdlite]

Timing of refs passed down from outside the Suspense boundary

There's another difference that's really a consequence of the same render-commit correspondence issue: the timing of refs passed in from a parent.

const refPassedFromParent = useRef(null)
<Suspense fallback={<Loading />}>
  <ComponentThatSuspends />
  <button ref={refPassedFromParent} {...buttonProps} />
</Suspense>

In Legacy Suspense, refPassedFromParent.current will point to a DOM node immediately on initial render, before ComponentThatSuspends resolved.

In Concurrent Suspense, refPassedFromParent.current will be null until ComponentThatSuspends resolves and the Suspense boundary is unblocked.

That means that any code in a parent that accesses that same ref will observe a change in the timing of when the ref resolves.

We think it's pretty unlikely that this will cause a difference in behavior, and in fact the new behavior is more consistent with the rest of React's rendering model. But it's worth calling out as something that could potentially affect existing code.

[chantastic]

This is a great point of clarification for the Concurrent Suspense mental model. Thanks for adding it.

[chantastic]

This is a great post, @acdlite! I appreciate how you jumped right to giving these things names: Legacy Suspense and Concurrent Suspense. This made it easy to track with the rest of the post.

I'm going to play my "no stupid questions" card. I find myself a little lost with render-commit language. I understand it in terms of Suspense boundaries (and this post) but I couldn't explain it in isolation.

Reading your post, I realized that I just don't think about the discrete render and commit phases (post-Hooks announcement). Is there a doc that clarifies the finer points of render and commit phases for Hooks?

[rickhanlonii]

One place that you may see the render and commit phases come up is when you're profiling performance. For example, consider an update caused by typing into the form field from the time-slicing demo deployed here:

Screen.Recording.2021-05-28.at.12.05.42.PM.mov

By default, React currently renders and commits updates synchronously. What that means, is that when you profile this interaction in DevTools, you'll see one long function call where React renders the tree to collect the updates and then commits the updates to the DOM all at once:

Here we have a render and commit phase, but the difference between them is not as clear because everything is synchronous.

When you switch this example over from "synchronous" to "concurrent", the only code we change is that we wrap the update in startTransition. This opts-in to concurrent rendering.

In concurrent rendering, React will yield during the render phase to other work in the browser, and to other React work at different priorities. This yielding allows other work to be done, which may schedule different updates at higher priority. For example, a promise may resolve and call setState to show new results on screen, which may be higher priority than other work that's not visible. When everything was synchronous, the promise wouldn't be handled until after the update finished, pushing out when this data is visible to the user. Yielding allows the promise to be handled while we're rendering, and tell React that we need to interrupt the current work for a higher priority update.

So when you profile this same interaction using a concurrent feature, the difference between the two phases is more clear. Now, the render phase is broken up into multiple tasks of smaller batches of work. In this phase we're collecting all of the updates we need to make and yielding every 5ms. Once we have all the updates, we start the commit phase. Here, we synchronously make all of the updates we need to make to the DOM.

This results in a flame graph that looks like this:

Note that this example is dramatized to show the effect. Generally, most of the work happens in the render phase followed by a relatively short commit. The point is, when you start seeing flame graphs that are broken up or stack traces with async boundaries, that's due to the render phase yielding!

[markerikson]

@rickhanlonii I think an explanation like this would be great to have in the docs themselves at some point!

[chantastic]

@rickhanlonii, I agree with @markerikson. this information is fantastic and would make a great post in explaining (and showing) the difference between legacy and Concurrent rendering.

I have a question about priority. If I understand correctly, ReactDOM.flushSync is a way to manipulate priority. Do you plan to talk about how to manipulate priority? Or is this a "trust us" part of React?

I tend to be fine with trusting React but know many developers aren't. They need to touch, taste, and experience the escape hatch. Seeing a document written from the perspective of manipulating priority might help set some folks at ease.

[gaearon]

Would this be best as a separate Q&A question? It seems like we're going on a tangent from the original topic about Suspense changes. This could be confusing for future readers.

[chantastic]

very fair. will open that up. thanks!

[ad1992]

Awesome post @acdlite 🎉 .

The difference is how a suspended component affects the rendering behavior of its siblings:
In Legacy Suspense, the Sibling component is immediately mounted to the DOM and its effects/lifecycles are fired. Then we hide it.
In Concurrent Suspense, the Sibling component is not mounted to the DOM. Its effects/lifecycles are also NOT fired until ComponentThatSuspends resolves, too. (This fixes some long-standing issues affecting component libraries.)

can we add CSB example for the two cases comparing legacy and concurrent suspense?

[gaearon]

I edited the post to add the sandboxes.

• React 17: https://codesandbox.io/s/keen-banach-nzut8?file=/src/App.js
• React 18 with createRoot: https://codesandbox.io/s/romantic-architecture-ht3qi?file=/src/App.js

The key difference is that in React 18, effects run after these logs:

===== fetched posts ===== 
===== fetched user ===== 

Whereas in React 17, they fire immediately even though the content is not visible yet.

[rickhanlonii]

Here's a more dramatized example (see the code comment for instructions to switch between 17 and 18, and toggle the console to see the difference).

[ad1992]

Thanks @gaearon @rickhanlonii for the examples 👍🏻
@rickhanlonii nitpick :) looks like a typo CM =>CR / create root ?

// In CM create Root , we properly suspend and the siblings are never mounted.

[rickhanlonii]

Fixed, thank you!

[liuyenwei]

This is a great post and I really appreciate the code examples since they do help clarify the differences.

We've been referring to the version of Suspense that exists in 16 and 17 as Legacy Suspense.

Does this mean that Legacy Suspense is completely removed in React 18 or is it the case where both exist and Concurrent Suspense only applies to subtrees that are opted into concurrent rendering?

In Legacy Suspense, the Sibling component is immediately mounted to the DOM and its effects/lifecycles are fired

Have you encountered any scenarios where this change in behavior did cause an issue? We have quite a few usages of Suspense in our codebase and, while most of them might not be impacted by this change, it does make me wonder if there are steps we can/should take to make the transition smoother.

[gaearon]

Does this mean that Legacy Suspense is completely removed in React 18 or is it the case where both exist and Concurrent Suspense only applies to subtrees that are opted into concurrent rendering?

Technically Legacy Suspense still exists in 18, but only for legacy roots (ReactDOM.render) which always warn and are a temporary strategy for migration. New roots (ReactDOM.createRoot) only use Concurrent Suspense.

Have you encountered any scenarios where this change in behavior did cause an issue? We have quite a few usages of Suspense in our codebase and, while most of them might not be impacted by this change, it does make me wonder if there are steps we can/should take to make the transition smoother.

The previous behavior definitely caused a bunch of issues related to prematurely firing effects, causing measurements too early.

The new behavior technically introduces semantic differences, like if your effects set some state on a parent component, you should keep in mind that this will now happen later than it might have happened before (because they run later). @rickhanlonii can speak to more details about how rolling out this change went for our surfaces.

[rickhanlonii]

So far, the only issue that has come up has been related to an unsafe shouldComponentUpdate that depends on mutable values. If we suspend, and then shouldComponentUpdate returns false, we won't commit the rendered content. This is what you want when shouldComponentUpdate only depends on props and state, but if you depend on some external state it can cause issues. Should be super uncommon. Here's a codesandbox.