Skip to content
Tutorials Center
My learning

Topics

React Reference ยท Components and Special Elements

The Suspense component

Reference for React Suspense: show a fallback while children wait for lazy components, use() promises or Suspense-enabled data, with rules and pitfalls.

Suspense shows a fallback while something inside it is not ready to render. "Not ready" can mean a component loaded with lazy whose code has not arrived yet, a promise read with use, or data from a framework or library that integrates with Suspense. When the thing is ready, React swaps the fallback for the real content.

A component signals "wait" by suspending: during rendering it reads something that is not available yet, and React stops rendering that part of the tree and looks for the nearest <Suspense> above it. The boundary does not need to know why its children are waiting.

JSX
import { Suspense } from 'react';

<Suspense fallback={<p>Loading...</p>}>
  <Profile />
</Suspense>

Try it

Waiting for a promise with use
A lazy component

Syntax

JSX
<Suspense fallback={fallbackNode}>{children}</Suspense>
Name Description
children The UI that may suspend.
fallback Any renderable node (usually a spinner or a skeleton) shown until all suspended children are ready. If the fallback itself suspends, the next boundary up handles it.

Returns: the children when ready, the fallback while waiting.

Edge cases: if a suspended component throws a rejection instead (a failed promise), Suspense does not catch it. Use an error boundary around the Suspense boundary for that.

Usage notes

  • What triggers it. Suspense activates for lazy() components, use(promise), and data libraries or frameworks built for it. A plain fetch inside useEffect does not suspend; the component renders immediately and you manage a loading flag yourself.
  • The promise must be stable. Calling use(fetch(...)) with a new promise on every render makes React wait forever for a new one. Create the promise outside the component, in a cache, or pass it in from a parent or Server Component.
  • State is preserved when content stays visible. If a boundary has already shown content and a later update suspends, React normally replaces that content with the fallback again unless the update runs inside a transition, which keeps the old UI visible.
  • Placement controls granularity. One boundary around a page shows one big spinner. Several smaller ones reveal parts independently. See Nested Suspense boundaries.
  • Effects wait. Effects of the suspended children do not run until they commit. Layout effects of already-visible siblings are cleaned up and re-run when the fallback appears and disappears.
  • Server rendering. With streaming server rendering, a boundary lets the server send the page shell first and the slow parts later; the fallback is part of the first HTML.
  • Accessibility. A spinner with no text tells screen reader users nothing. Include text, or use role="status" on a message.
  • Layout shift. A fallback that is much smaller than the content makes the page jump. Reserve space with a skeleton of similar size.