Suspense List
In one line
Suspense List controls the reveal order of multiple Suspense boundaries — prevents layout jumps.
In simple words
Suspense List (still experimental in React 18) coordinates how multiple Suspense boundaries reveal their content. Without it, each boundary reveals independently as its data loads — causing layout jumps and jarring reordering.
With Suspense List, you can specify:
reveal="together"— wait for all, reveal at oncereveal="forwards"— reveal in order, skip ahead if earlier ones aren't readyreveal="backwards"— reveal in reverse order
This prevents flash-of-wrong-content and layout shifts when multiple async sections load at different times. Note: this API is still experimental and may change.
Example
import { SuspenseList, Suspense } from "react";
function Profile({ userId }) {
return (
<SuspenseList reveal="together">
<Suspense fallback={<Spinner />}>
<Header userId={userId} />
</Suspense>
<Suspense fallback={<Spinner />}>
<Bio userId={userId} />
</Suspense>
<Suspense fallback={<Spinner />}>
<Posts userId={userId} />
</Suspense>
</SuspenseList>
);
}SuspenseList with reveal='together' waits until all three sections are loaded, then reveals them simultaneously — no layout jumps.
Common confusions
Confused with: Suspense
The difference: Suspense wraps a single async boundary and shows a fallback while waiting. SuspenseList wraps multiple Suspense boundaries and coordinates their reveal order. Suspense handles one loader; SuspenseList orchestrates multiple loaders.
Related terms
Related Resources
Related Lessons
- React 18 Features
Suspense List.
Decode error messages
Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.