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.
import { Suspense } from 'react'; <Suspense fallback={<p>Loading...</p>}> <Profile /> </Suspense>
Try it
Syntax
<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 plainfetchinsideuseEffectdoes 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.