React Reference ยท Components and Special Elements
Nested Suspense boundaries
Place several Suspense boundaries inside each other to reveal a page in stages, keep old content visible with transitions, and avoid a wall of spinners.
A component that suspends looks upward for the nearest <Suspense> and shows that boundary's fallback. If you nest boundaries, each part of the page waits independently: fast parts appear early and slow parts keep their own small fallback. If you use a single boundary around everything, nothing appears until the slowest piece is ready.
Choosing where to put boundaries is a design decision, not a technical one. Ask: which pieces of UI should appear together, and which should be allowed to arrive later without disturbing what is already on screen?
<Suspense fallback={<PageSkeleton />}> <Header /> <Suspense fallback={<FeedSkeleton />}> <Feed /> </Suspense> </Suspense>
Try it
In the first example the title appears after about 0.3 seconds with "Loading table..." under it, and the list replaces that after about 1.2 seconds. The page is usable earlier than if everything had to wait.
In the second example the first load shows "Loading tab..." because there is nothing yet to keep. After that, clicking Stats for the first time dims the old content and shows "Switching..." instead of replacing it with the fallback, because the state change runs inside a transition. Clicking Home again is instant, since its promise is cached.
Syntax
There is no special syntax: nesting is plain JSX. The rules that decide what shows are:
| Situation | What React shows |
|---|---|
| A child suspends and an inner boundary exists | The inner boundary's fallback. Outer content stays. |
| A child suspends and only an outer boundary exists | The outer fallback replaces the whole outer boundary's content. |
| The outer boundary is still waiting | The inner boundary has not started revealing yet. The outer fallback shows. |
| An update suspends outside a transition, content already visible | The boundary goes back to its fallback. |
| An update suspends inside a transition | The old UI stays and isPending becomes true. A boundary that has already revealed content is not hidden again. |
Usage notes
- A boundary is a loading unit. Content inside it appears together. Wrap things that make sense only as a set (a chart and its legend); keep unrelated widgets in separate boundaries.
- Do not wrap every component. A spinner for each tiny piece creates a popcorn effect where many things pop in one by one. Group by region of the page.
- Fallbacks should match the layout. Skeletons with similar sizes avoid layout shift when the real content arrives.
- New boundaries during a transition. A boundary that appears for the first time in an update inside a transition does show its fallback, so something visible happens even when the rest of the page stays put.
- Avoid waterfalls. If a child starts its fetch only after its parent has finished loading, the requests run one after another. Start independent requests early (above the boundaries, in a cache, or on the server) and let components read them.
- Errors are separate. A rejected promise goes to the nearest error boundary, not to Suspense. Combine them: error boundary outside, Suspense inside.
- Server rendering. With streaming, each boundary can be flushed on its own as soon as its content is ready, which is why fine-grained boundaries help first paint.