---
title: "Suspense boundary"
slug: "suspense-boundary"
category: "glossary"
tags: ["glossary", "frontend", "react", "async", "rendering", "streaming"]
status: "stable"
last_updated: 2026-05-14
summary: "A Suspense boundary is a React component that catches async loading states in its subtree and shows a fallback UI until data or code is ready."
related:
  [
    "[[frontend/react]]",
    "[[frontend/nextjs]]",
    "[[glossary/code-splitting]]",
    "[[glossary/hydration]]",
    "[[glossary/server-component]]",
    "[[glossary/virtual-dom]]",
  ]
---

## Overview

This page is the atomic definition. React streaming and async patterns live at [[frontend/react]] and [[frontend/nextjs]].

## Definition

A Suspense boundary is a `<Suspense fallback={<Spinner />}>` wrapper that catches "not ready" signals from its child subtree. When a child component throws a Promise (the mechanism React uses for lazy-loaded code and data), the nearest ancestor Suspense boundary catches the throw, renders the `fallback` prop instead, and resumes rendering the child when the Promise resolves. This enables streaming HTML: Next.js App Router can flush the HTML shell to the browser immediately and stream each Suspense-bounded section as its data resolves, reducing Time to First Byte and improving perceived load speed. Nesting boundaries gives fine-grained control: a spinner per card rather than one full-page spinner. Error boundaries (a separate construct) catch synchronous throws; Suspense boundaries catch async throws.

## When it applies

Wrap every `React.lazy()` import with a Suspense boundary. In Next.js App Router, Suspense boundaries define streaming units, so place them around sections that depend on slow data sources. Avoid a single root boundary that blocks the entire page.

## Example

```jsx
import { Suspense, lazy } from "react"
const HeavyChart = lazy(() => import("./HeavyChart"))

function Dashboard() {
  return (
    <div>
      <Header />
      <Suspense fallback={<ChartSkeleton />}>
        <HeavyChart />
      </Suspense>
    </div>
  )
}
```

## Related concepts

- [[frontend/react]] - the full React rendering model including concurrent features.
- [[frontend/nextjs]] - Next.js App Router uses Suspense for streaming SSR.
- [[glossary/code-splitting]] - React.lazy requires a Suspense boundary.
- [[glossary/hydration]] - each Suspense-bounded island hydrates independently.
- [[glossary/server-component]] - Server Components and Suspense compose to enable streaming.

## Citing this term

> See [[glossary/suspense-boundary|Suspense boundary]] (llmbestpractices.com/glossary/suspense-boundary).

## Related

- [[frontend/react]]
- [[frontend/nextjs]]
- [[glossary/code-splitting]]
- [[glossary/hydration]]
- [[glossary/server-component]]