React Reference ยท Concepts and Pitfalls
How Suspense works
A mental model of React Suspense: what it means to suspend, which boundary shows the fallback, why promises must be stable and how transitions avoid fallbacks.
Suspense lets a component say "I cannot render yet" in the middle of rendering. A component that suspends stops its own render. React then walks up the tree, finds the nearest <Suspense> boundary and renders that boundary's fallback instead. When the thing the component was waiting for becomes ready, React tries again from the boundary and swaps the real content in.
Historically a suspending component literally threw a promise, and React caught it. That protocol is an internal detail of React and of Suspense-enabled libraries; in your own code you suspend by calling use(promise), by rendering a lazy component, or by using a framework or data library that does it for you.
<Suspense fallback={<Spinner />}> <Comments postId={id} /> {/* may suspend while reading data */} </Suspense>
Try it
The header resolves first and the page appears with the sidebar's own fallback still showing. The inner boundary catches the slower part so it does not hold back the rest of the page.
The first load always shows the fallback because nothing has been revealed yet. After that, the plain button replaces the profile with the fallback again, while the transition button keeps the old profile on screen until the new one is ready.
The rules of the model
- The nearest boundary wins. Suspending climbs to the closest
<Suspense>above the component. With no boundary at all there is no fallback to show, so the root itself has to wait (or React reports an error for a synchronous update). Wrap the parts that can load in their own boundary. - Work in the suspended subtree is thrown away. On first mount, React does not commit the component that suspended, and none of its state or effects exist yet. The fallback is committed instead.
- Already visible content is hidden, not destroyed. If content that has been shown suspends again (for example, a new
idprop reads a new promise), React hides it withdisplay: noneand shows the fallback. Its state survives; its layout effects are cleaned up and re-run when it is revealed. - Siblings before the boundary are unaffected. Only the subtree inside the boundary swaps to the fallback.
- Transitions refuse to hide revealed content. An update inside
startTransitionthat would suspend an already-visible boundary keeps the old UI and reportsisPendinginstead. New boundaries that have never been revealed still show their fallback. - Server rendering streams boundaries. With streaming APIs the server can send the page with fallbacks and fill the rest in when data arrives (see Streaming and Suspense).
Promises must be stable
A suspending component is rendered again after the promise settles, and React needs to read the same promise each time to get the result. Creating a promise inside a Client Component's render, like use(fetch(url)), makes a new promise on every attempt, so it never settles from React's point of view. React reports an error about an uncached promise. Create the promise outside render, cache it (as above), or receive it from a Server Component or a Suspense-aware library.
Usage notes
- Fallback placement is a design decision. A boundary high in the tree hides a lot of content when anything inside suspends; many small boundaries cause a "popcorn" of spinners. Group things that should appear together.
- Fallbacks should be cheap and layout-stable, such as skeletons with the same size as the final content.
- Errors are separate. A rejected promise read by
usethrows during render and is handled by an error boundary, not by Suspense. - Effects and event handlers do not suspend. Only rendering can suspend; fetching in an effect is a different pattern.
lazycomponents suspend until their module loads, and React remembers the result for later renders.- Server and client share the model. Hydration can wait for a suspended boundary while the rest of the page becomes interactive (see Hydration).