Suspense Basics

Suspense lets you declare what to show while something below it is not ready. Instead of every component managing its own loading flag, a boundary higher up handles it for the whole subtree.

<Suspense fallback={<ProfileSkeleton />}>
  <ProfileHeader />
  <ProfileTimeline />
</Suspense>

If either child suspends, React shows the fallback in place of the whole boundary until everything inside is ready.

What can suspend

• Components loaded with lazy, while their chunk downloads.
• Data reads from a framework or library with Suspense support - Next.js, Relay, or TanStack Query in suspense mode.
• A promise passed to the use hook in React 19.

Placing boundaries deliberately

A boundary's granularity decides what the user sees. One boundary around the whole page means an all-or-nothing skeleton; several smaller ones let parts arrive independently.

// The whole page waits for the slowest piece
<Suspense fallback={<PageSkeleton />}>
  <Header />
  <SlowFeed />
  <Sidebar />
</Suspense>

// Header and Sidebar appear immediately
<Header />
<Suspense fallback={<FeedSkeleton />}>
  <SlowFeed />
</Suspense>
<Sidebar />

Nested boundaries

Boundaries nest, and the nearest one wins. That lets an outer boundary cover the initial load while inner ones handle their own slower pieces.