Suspense

React · Reference cheat sheet

📋 Overview

<Suspense fallback=\{...\}> shows fallback UI while children are loading (lazy components, React 19 resource reading patterns, frameworks with RSC/data). Pair with lazy() for code-splitting and error boundaries for failures.

🔧 Core concepts

• Boundary — catches “suspend” from descendants; shows fallback.
• React.lazy — dynamic import() wrapped component.
• Nested — nearest boundary handles the suspend.
• Transitions — pending transitions can avoid hiding already-shown UI (concurrent).
• Not for — ordinary useEffect fetching unless integrated with a Suspense-aware data API.

💡 Examples

import { lazy, Suspense } from "react";

const Editor = lazy(() => import("./Editor"));

export function Page() {
  return (
    <Suspense fallback={<p>Loading editor…</p>}>
      <Editor />
    </Suspense>
  );
}

Nested boundaries:

<Suspense fallback={<PageSkeleton />}>
  <Header />
  <Suspense fallback={<FeedSkeleton />}>
    <Feed />
  </Suspense>
</Suspense>

Named export lazy:

const Chart = lazy(() =>
  import("./Chart").then((m) => ({ default: m.Chart })),
);

⚠️ Pitfalls

• Missing error boundary—load failures are not Suspense.
• One giant boundary → whole page flashes fallback.
• Suspense for data without a compatible library/framework → won’t suspend.
• Forgetting a default export when using lazy(() => import(...)).

🔗 Related

• error_boundaries.md — failures
• concurrent.md — concurrent UI
• useTransition.md — pending states
• performance.md — code splitting
• router.md — route-level lazy