Code splitting with lazy
A component's JavaScript module is loaded on demand and may suspend on first render.
React 19+ · Component
Suspense
Suspense displays a fallback while descendant UI is not ready, then reveals that UI when it can render. Use boundaries to define loading regions and coordinate progressive or streamed content.
How it works
Suspense creates a boundary around child UI that may not be ready during rendering. When a child suspends, React temporarily renders the fallback; once the child is ready, React replaces the fallback with the child content. Boundaries can also coordinate progressive loading and server-rendered streaming.
Syntax
<Suspense fallback={fallback}>{children}</Suspense>Parameters
| Name | Type | Description |
|---|---|---|
children | ReactNode | The React nodes to render when ready. If they suspend during rendering, the boundary renders fallback instead. |
fallback | ReactNode | The alternate React node shown while children have not finished loading. |
Returns
A React element that renders children when ready and fallback while children are suspended.
Key points
- Wrap potentially delayed UI in a Suspense boundary to provide declarative loading behavior.
- The children prop contains the UI that the boundary protects.
- The fallback prop supplies the temporary UI shown while the protected content is unavailable.
- React changes between fallback and children automatically as the boundary's readiness changes.
- Code loaded through React.lazy can suspend, making Suspense the place to present its loading state.
- Promise-based rendering with use can keep a boundary from revealing content until the value is available.
- Suspense boundaries can be positioned around any application subtree to establish a loading region.
Common mistakes
- A fallback can itself suspend; React then uses the nearest enclosing Suspense boundary.
- An already visible boundary may switch to its fallback during an update; use startTransition for non-urgent updates to avoid that undesirable replacement.
- Suspended content is revealed with batching behavior, so multiple boundaries that become ready within the interval may appear together.
Example: Lazy component with a loading boundary
import { Suspense, lazy } from 'react';
const Preview = lazy(() => import('./Preview.js'));
export default function App() {
return (
<Suspense fallback={<p>Loading preview…</p>}>
<Preview />
</Suspense>
);
}A lazy component suspends while its module loads, so the boundary displays a lightweight fallback and then renders the loaded component.
When to use it
Progressive loading with nested boundaries
Different parts of a page become ready at different times and should reveal in coordinated groups.
Streaming server rendering
Server-rendered content can be sent in independently renderable regions.
Interview questions
QWhat problem does Suspense solve, and when does it show the fallback?
Suspense renders its fallback when a descendant suspends while rendering, then switches back to the children when they are ready. A suspended boundary can wait for lazy component code, a Promise read with use, or certain stylesheet loads.
Follow-up: How would you avoid hiding content that is already visible during navigation? Wrap the non-urgent update in startTransition so React can delay the fallback replacement.
QWhat makes a good Suspense fallback?
The fallback is an alternate React node rendered in place of unfinished children. It should usually be lightweight, such as a spinner or skeleton, and it must not itself suspend unless an enclosing boundary can handle that suspension.
Follow-up: What happens if the fallback suspends? React activates the closest parent Suspense boundary.
QHow can Suspense coordinate progressive loading and server rendering?
Suspense boundaries let an application choose which regions reveal together and which progressively reveal through nested loading states. During server rendering, React includes the fallback in the HTML and later replaces it in the browser with the saved content.
Follow-up: How can a server-rendered page reveal independent regions sooner? Place separate Suspense boundaries around regions that can load independently, allowing their content to stream separately.
Related
lazyusestartTransitionServer Components