On this page

04. What is a Suspense boundary?

📄 Noteseasy#suspense#boundaries#architecture

Short answer

A Suspense boundary is a <Suspense fallback={...}> element and the subtree it wraps. When any component inside that subtree suspends, the nearest boundary above it takes over and shows its fallback for that whole region. Boundaries define the units of your UI that load (and, with SSR, stream and hydrate) together.

Explanation

Analogy: fire doors in a building. A fire (suspension) in one room is contained by the nearest fire door; the rest of the building carries on. Where you place the doors decides how much of the building is closed off.

Properties of a boundary

  • Nearest wins: a suspension bubbles up the fiber tree to the closest Suspense ancestor, like errors bubble to the closest error boundary.
  • All-or-nothing: everything inside one boundary reveals together, even siblings that were already ready.
  • Isolation: sibling boundaries load independently.
  • State preservation: when an update re-suspends already shown content, the children are hidden, not unmounted.
  • SSR unit: each boundary is a chunk that can be streamed and hydrated on its own.

Choosing boundary placement

PlacementEffect
One boundary at the app rootWhole app shows one spinner; simple but blunt
One per page section (header, feed, sidebar)Good default: meaningful regions load independently
One per list item / tiny widgetSpinner soup and layout shift
Route level (loading.js in Next.js)Framework creates a boundary per route segment

Ask: "What should the user see together?" Group content that makes sense only as a unit in one boundary.

<App>
 ├─ <Header/>                      (no suspense, always shown)
 ├─ <Suspense fallback=FeedSkeleton>
 │    ├─ <Feed/>        suspends -> FeedSkeleton shown
 │    └─ <FeedFilters/> ready, but hidden with Feed (same boundary)
 └─ <Suspense fallback=SidebarSkeleton>
      └─ <Sidebar/>     independent

Example

import { Suspense } from "react";
import { ErrorBoundary } from "react-error-boundary";

export default function Home() {
  return (
    <Layout>
      <Header />
      <ErrorBoundary fallback={<p>Feed failed to load.</p>}>
        <Suspense fallback={<FeedSkeleton />}>
          <FeedFilters />
          <Feed />
        </Suspense>
      </ErrorBoundary>
      <Suspense fallback={<SidebarSkeleton />}>
        <Sidebar />
      </Suspense>
    </Layout>
  );
}

Common mistakes

  • No boundary above a suspending component. With no boundary at all, React 19 has nothing to show while waiting; on the client the root stays empty or unchanged, which looks like a frozen page.
  • Too many boundaries, causing many skeletons popping in separately.
  • Forgetting an error boundary next to it; rejections aren't handled by Suspense.
  • Assuming portals escape the boundary. Suspensions bubble through the React tree, not the DOM tree, so a portal's content is still caught by its React ancestor's boundary.

Follow-up questions

  • How is it similar to an error boundary? Both catch something thrown during render and show alternative UI, using the nearest ancestor.
  • Can a fallback itself suspend? It can, and it bubbles to the next boundary up, but avoid it; fallbacks should be cheap and synchronous.
  • Do boundaries affect performance? They're cheap. The cost is UX: too few is blunt, too many is noisy.

Quick recap

  • Boundary = Suspense + subtree.
  • Nearest boundary catches a suspension.
  • Everything inside reveals together.
  • Place around meaningful regions.
  • Pair with error boundaries.