On this page

08. How does nested Suspense work?

📄 Notesmedium#suspense#nesting#progressive-loading#internals

Short answer

When boundaries are nested, a suspension goes to the innermost boundary that wraps the suspending component. The outer boundary waits only for content that isn't covered by an inner boundary. This gives progressive reveal: first the outer shell appears with the inner fallbacks in place, then each inner region fills in as its data arrives. An inner region can never appear before its outer boundary has revealed.

Explanation

Analogy: Russian dolls, or a house being built. The outer structure (walls and roof) must be up before rooms can be furnished; each room is then furnished on its own schedule.

Reveal sequence

<Suspense fallback=PageSpinner>        (outer)
  <Article/>                           needs article data
  <Suspense fallback=CommentsSkeleton> (inner)
    <Comments/>                        needs comments data
  </Suspense>
</Suspense>

t=0     PageSpinner (Article pending)
t=300   Article + CommentsSkeleton     (outer resolved, inner still pending)
t=900   Article + Comments             (inner resolved)

If comments arrive first (t=100): still PageSpinner until t=300,
then Article and Comments appear together.

Rules

RuleConsequence
Innermost boundary catchesInner suspensions don't affect the outer region
Outer must reveal firstInner content can't show while outer is on its fallback
Outer waits for its direct contentComponents not wrapped by an inner boundary hold the outer back
Fallbacks are part of the parentAn inner fallback is shown as normal content of the outer boundary
Reveal throttlingReact batches nested reveals that happen close together (about 300 ms) to reduce flicker

Designing nested boundaries

  • Outer boundary: essential content (title, main body) that defines the page.
  • Inner boundaries: secondary, slower content (comments, recommendations, related items).
  • Matches streaming SSR well: the shell and article stream first, comments stream later.

Example

import { Suspense } from "react";

export default function PostPage({ postPromise, commentsPromise, relatedPromise }) {
  return (
    <Suspense fallback={<PageSkeleton />}>
      <Post postPromise={postPromise} />

      <Suspense fallback={<CommentsSkeleton />}>
        <Comments commentsPromise={commentsPromise} />

        <Suspense fallback={<p>Loading related posts...</p>}>
          <Related relatedPromise={relatedPromise} />
        </Suspense>
      </Suspense>
    </Suspense>
  );
}

Here Related can only appear after Comments, and Comments only after Post. If you want Related independent of Comments, make them siblings rather than nesting one inside the other.

Common mistakes

  • Nesting when you meant siblings, which unintentionally ties reveal order to the parent.
  • Leaving a slow component directly in the outer boundary, holding the whole page on the spinner.
  • Deep nesting with tiny regions, causing a staircase of skeletons.
  • Assuming an inner region that resolved first will appear first. It waits for the outer.

Follow-up questions

  • How does nesting interact with transitions? If an update inside a transition suspends in a newly mounted inner boundary, that inner fallback shows (it's new), while already revealed outer content stays.
  • How is this used in Next.js? Nested loading.js files in route segments create nested boundaries automatically.
  • Does nesting cause request waterfalls? Not by itself; waterfalls come from starting fetches inside components that only render after the parent resolves.

Quick recap

  • Innermost boundary catches the suspension.
  • Outer reveals before inner, never the reverse.
  • Outer waits only for uncovered content.
  • Use nesting for primary vs secondary content.
  • Siblings, not nesting, for independent regions.