Suspense placement

Suspense reveals content at the granularity of its boundary — the boundary is the unit of “appears together”. Everything inside one <Suspense> is treated as one atomic chunk: React shows the fallback until every suspending child under it has resolved, then reveals all of them at once. So the boundary isn’t just “where the spinner goes” — it defines which slice of the UI lives and dies together.

// Everything under this ONE boundary appears together.
// If <SlowFeed> takes 1.2s, <FastHeader> and <FastSidebar>
// are hidden behind the fallback for the full 1.2s too.
<Suspense fallback={<PageSkeleton />}>
  <FastHeader />
  <FastSidebar />
  <SlowFeed />
</Suspense>

The lesson of this whole unit falls out of that sentence: if you want two parts of the page to reveal independently, they need to be under two boundaries.

Place boundaries close to where the data is needed, not only at the route root. The instinct from older patterns is one loading state per page. Suspense rewards the opposite: push the boundary down so the static shell and already-resolved data paint immediately, and each slow region carries its own fallback. The page becomes a set of independently-streaming holes in an otherwise-instant layout.

// The shell + header + nav are instant. Each slow region
// streams into its own slot behind its own fallback.
export default function Dashboard() {
  return (
    <DashboardShell>
      <Header />            {/* paints immediately */}
      <Suspense fallback={<FeedSkeleton />}>
        <ActivityFeed />    {/* streams in when ready */}
      </Suspense>
      <Suspense fallback={<StatsSkeleton />}>
        <RevenueStats />    {/* streams in independently */}
      </Suspense>
    </DashboardShell>
  );
}

Now a slow <RevenueStats> never holds the feed hostage, and neither holds the shell hostage. The user sees structure in 80ms and watches content fill in — far better perceived performance than one long blank.

One root boundary is all-or-nothing; granular boundaries reveal content progressively as it arrives. This is the core tradeoff. A single top-level Suspense gives you the simplest code and the worst experience for unbalanced load times: the page reveals at the speed of its slowest child. Granular boundaries cost a few more components but let each region reveal at the speed of its own data.

// ❌ all-or-nothing: page appears at the speed of the SLOWEST child
<Suspense fallback={<FullPageSpinner />}>
  <Header /><Feed /><Stats /><Recommendations />
</Suspense>

// ✅ progressive: each region appears at the speed of ITS OWN data
<Header />
<Suspense fallback={<FeedSkeleton />}><Feed /></Suspense>
<Suspense fallback={<StatsSkeleton />}><Stats /></Suspense>
<Suspense fallback={<RecsSkeleton />}><Recommendations /></Suspense>

In the streaming SSR / RSC model this is literal network streaming: the server flushes the shell and each boundary’s content as it resolves, so granular boundaries don’t just change when React reveals — they change what bytes arrive first.

The failure mode: a single top-level Suspense that blanks the entire page whenever any small part is loading. This is the anti-pattern this lesson exists to kill. A lonely analytics widget, a “people you may follow” list, a non-critical chart — any one of them suspending will hide your entire, otherwise-ready page behind the root fallback. The user pays the slowest component’s latency to see the fastest content.

// One slow, low-priority widget holds the whole page hostage.
<Suspense fallback={<FullPageSpinner />}>
  <CriticalArticle />     {/* ready in 90ms... */}
  <RelatedPosts />        {/* ...but blocked 1.4s by this */}
</Suspense>

But the inverse is also a failure: a boundary around every leaf produces a flickering mess of skeletons and shifting layout that reads as jank, not progress. So the discipline is matching boundaries to meaningful independent load regions — wrap things that have genuinely different timings the user benefits from seeing resolve separately, and let things that load together share one boundary. Boundary placement is a judgment call about which chunks should appear together.