Skip to content

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 once
  • reveal="forwards" — reveal in order, skip ahead if earlier ones aren't ready
  • reveal="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

jsx
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

Decode error messages

Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.

View errors

← Back to glossary