Suspense

A loading state you describe once

In Fetching data, every component that loaded something kept its own loading state: a null to start from, a check, and a Loading… line. Suspense moves that job out of the component. <Suspense> is a component that comes with React. You wrap part of the page in it and give it a fallback: what to show while anything inside is still waiting. Here the reviews come from a pretend server in the data.js tab, which answers after 1.5 seconds; nothing goes over the network. The result is live; press Run again to watch it load.

1import { Suspense, use } from "react";2import { fetchData } from "./data.js";3 4function Reviews() {5  const reviews = use(fetchData("/reviews/tea"));6  return (7    <ul>8      {reviews.map((review) => <li key={review}>{review}</li>)}9    </ul>10  );11}12 13export default function ProductPage() {14  return (15    <>16      <h2>Green tea</h2>17      <Suspense fallback={<p>Loading reviews…</p>}>18        <Reviews />19      </Suspense>20    </>21  );22}

Line 5 calls fetchData("/reviews/tea"), which returns a promise, and reads it with use, an API from React. While the promise hasn't resolved, use can't give back the reviews, so it stops Reviews from rendering. That's called suspending. React then looks for the nearest <Suspense> above it, the Suspense boundary on lines 17 to 19, and shows its fallback, Loading reviews…. The heading on line 16 is outside the boundary, so it shows at once.

When the promise resolves, React renders Reviews again. This time use returns the array, line 8 lists it, and the boundary swaps its fallback for its children, the components inside it. Notice what Reviews doesn't have: no null check and no loading message. It's written as if the data were already there, and the boundary owns the waiting.

Open the data.js tab. fetchData on lines 6 to 9 keeps every promise in a Map, so each key is loaded once, and every read of it gets the same promise back. That cache matters a lot, as the next section shows. The console says Load /reviews/tea once, from line 19.

What can make a component wait

Suspense only reacts to components that suspend while they render. In React 19, a component suspends when it:

• reads a promise with use before that promise has resolved, where the promise comes from a cache, as in data.js. The next lesson, The use API, covers use in full;
• renders a component made with lazy whose code hasn't downloaded yet, which a later section covers;
• reads data the way a Suspense-enabled framework, like Next.js or Relay, gives it to you. Inside, these keep a cache of their data and suspend for you.

A request in an effect isn't on the list. Here is the Fetching data way, inside a boundary:

1import { Suspense, useEffect, useState } from "react";2import { fetchData } from "./data.js";3 4function Reviews() {5  const [reviews, setReviews] = useState(null);6  useEffect(() => {7    fetchData("/reviews/tea").then((data) => setReviews(data));8  }, []);9  if (reviews === null) return <p>Reviews' own loading message</p>;10  return (11    <ul>12      {reviews.map((review) => <li key={review}>{review}</li>)}13    </ul>14  );15}16 17export default function ProductPage() {18  return (19    <>20      <h2>Green tea</h2>21      <Suspense fallback={<p>Suspense fallback</p>}>22        <Reviews />23      </Suspense>24    </>25  );26}

The result shows Reviews' own loading message from line 9, never Suspense fallback from line 21. Reviews rendered fine on its first try: it returned a paragraph. The effect on lines 6 to 8 runs after that, and React doesn't know it started a request. Suspense never hears about requests in effects or event handlers.

Why does the promise have to come from a cache? Here a component makes its promise while it renders, which is wrong on purpose:

1import { Suspense, use } from "react";2 3// Wrong on purpose: every call makes a new promise.4function loadReviews() {5  console.log("Load /reviews/tea");6  return new Promise((resolve) => {7    setTimeout(() => resolve(["Fresh and light.", "Great with lunch."]), 1500);8  });9}10 11function Reviews() {12  const reviews = use(loadReviews());13  return (14    <ul>15      {reviews.map((review) => <li key={review}>{review}</li>)}16    </ul>17  );18}19 20export default function ProductPage() {21  return (22    <>23      <h2>Green tea</h2>24      <Suspense fallback={<p>Loading reviews…</p>}>25        <Reviews />26      </Suspense>27    </>28  );29}

Line 12 calls loadReviews during every render, and line 6 makes a new promise each time. After 1.5 seconds the first promise resolves, so React renders Reviews again. That render calls loadReviews again, which makes a new promise that hasn't resolved, so Reviews suspends again. The fallback never goes away, and the count beside Load /reviews/tea in the console keeps going up, every 1.5 seconds. (It starts at 2: once the fallback is on the screen, React renders Reviews once more to start its loading early, a pre-warm that a later section explains.) Nothing turns red; the page just never finishes. That's why data for use comes from a cache: data.js's Map, a framework, or a data library, which hand out the same promise for the same data.

How to read the table: each row is something a component does, whether the nearest boundary shows its fallback, and why.

One boundary shows its content together

A boundary is one unit: it shows all of its children, or its fallback. Put two waiting components in one boundary, and it waits for both. The product page below has its details and its reviews in their own files, the Details.jsx and Reviews.jsx tabs. Each reads its own data with use on its line 5: the product takes 0.6 seconds and the reviews 1.5.

1import { Suspense } from "react";2import Details from "./Details.jsx";3import Reviews from "./Reviews.jsx";4 5export default function ProductPage() {6  return (7    <Suspense fallback={<p>Loading the product…</p>}>8      <Details productId="tea" />9      <Reviews productId="tea" />10    </Suspense>11  );12}

Lines 7 to 10 put both components in one boundary. At 0.6 seconds the details are ready, but React doesn't show them, because Reviews is still waiting. At 1.5 seconds both appear together. Both requests start straight away: the console shows Load /products/tea and Load /reviews/tea as the page opens, so there's no waterfall. The wait is the slower of the two, not their sum.

Use one boundary when the parts only make sense together, like a chart and its legend. Then the reader never sees one without the other.

Nested boundaries reveal the page in steps

When one part is quick and useful on its own, give the slow part a boundary of its own, inside the first one:

1import { Suspense } from "react";2import Details from "./Details.jsx";3import Reviews from "./Reviews.jsx";4 5export default function ProductPage() {6  return (7    <Suspense fallback={<p>Loading the product…</p>}>8      <Details productId="tea" />9      <Suspense fallback={<p>Loading reviews…</p>}>10        <Reviews productId="tea" />11      </Suspense>12    </Suspense>13  );14}

Lines 9 to 11 wrap Reviews in a second boundary, inside the outer one on lines 7 to 12. A boundary waits only for the components inside it that aren't inside a nested boundary, so the outer one now waits only for Details. Press Run again and watch three moments:

1. At first, Loading the product…, the outer fallback.
2. At 0.6 seconds, the heading Green tea: $3, with the inner fallback Loading reviews… under it.
3. At 1.5 seconds, the reviews in place of the inner fallback.

Where you put boundaries is a design choice, not a technical one. Put them where a person would expect a separate loading state: the main content, a sidebar, a list of comments. Don't wrap every component: a page that pops in piece by piece is jumpy and hard to read. In the playground, load the same page with one boundary or two, and with slow or quick reviews. Each row is a moment the screen changed, timed from the load.

With One boundary, the heading waits for the reviews, until 1.5 seconds. With nested boundaries, it comes at 0.6 seconds and the reviews at 1.5. Then choose Reviews take 0.7 s with nested boundaries. The reviews are ready only 0.1 seconds after the details, but they appear at about 0.9 seconds. React reveals content at most once every 300 ms, counted from the last time a fallback appeared or was replaced, so the page doesn't flicker through steps that are only a moment apart.

Boundaries matter on a server too. When a framework renders the page on a server, it can send the HTML outside the boundaries first, with the fallbacks, and then each boundary's content once it's ready. Since React 19.2, reveals that come close together are grouped there too. Streaming server rendering covers that.

React 19 shows the fallback first

What happens to the siblings of a component that suspends, like Reviews next to Details in one boundary? This changed in React 19, as its upgrade guide describes:

• React 18 rendered every sibling first, and only then showed the fallback.
• React 19 shows the fallback as soon as one component suspends. Then it renders the skipped siblings in a separate pass, to start whatever they load early. That pass is called pre-warming.

You can watch it. The fallback below is a Spinner component that logs from an effect, and an effect only runs once its component is on the screen:

1import { Suspense, useEffect } from "react";2import Details from "./Details.jsx";3import Reviews from "./Reviews.jsx";4 5function Spinner() {6  useEffect(() => {7    console.log("Fallback on screen");8  }, []);9  return <p>Loading the product…</p>;10}11 12export default function ProductPage() {13  return (14    <Suspense fallback={<Spinner />}>15      <Details productId="tea" />16      <Reviews productId="tea" />17    </Suspense>18  );19}

The console says Load /products/tea, then Fallback on screen (with a 2: StrictMode runs a new effect twice in development), and only then Load /reviews/tea. Details on line 15 suspended, so React skipped Reviews on line 16, put Spinner on the screen, and then rendered Reviews in a pre-warm, whose fetchData started the reviews request. In React 18, Load /reviews/tea came before Fallback on screen.

React's own code says so. When a component suspends, React leaves it and walks up to the nearest boundary; this excerpt from ReactFiberWorkLoop.js decides what happens to the siblings on the way:

      // This is not a prerender. Skip the siblings during this render. A
      // separate prerender will be scheduled for later.
      skipSiblings = true;
      workInProgressRootDidSkipSuspendedSiblings = true;

In plain words, line by line:

1. This render isn't a pre-warm, so don't render the siblings now.
2. A separate pre-warm render will be scheduled for later.
3. skipSiblings = true makes React go straight up to the boundary, past Reviews.
4. React notes that it skipped siblings, so that it schedules the pre-warm once the fallback is on the screen.

The result: the reader sees a loading state sooner, and the siblings' loading still starts before they're shown. A pre-warm render is never shown and never runs effects; it only starts loading. That's one more reason to load data while rendering, through a cache, instead of in effects: a request in an effect can't start until its component is on the screen.

Don't hide what's already on screen

Once a boundary shows its content, a component inside it can still suspend later, for example when it needs new data. Here you can switch between two products:

1import { Suspense, useState } from "react";2import Details from "./Details.jsx";3import Reviews from "./Reviews.jsx";4 5export default function ProductPage() {6  const [productId, setProductId] = useState("tea");7  return (8    <>9      <button onClick={() => setProductId("tea")}>Tea</button>10      <button onClick={() => setProductId("cake")}>Cake</button>11      <Suspense fallback={<p>Loading the product…</p>}>12        <Details productId={productId} />13        <Reviews productId={productId} />14      </Suspense>15    </>16  );17}

Line 6 keeps the picked product, and line 10 switches to cake. Wait for tea to load, then click Cake. Cake's data isn't in the cache yet, so Details suspends, and the boundary on lines 11 to 14 hides tea and shows Loading the product… again, for 1.2 seconds. React doesn't throw tea's content away: it hides it with display: none and keeps its state. Now click Tea: it shows at once, because its promise is in the cache and has resolved, so use returns its value straight away.

That flash is unpleasant: you were reading about tea, and it vanished. A transition tells React that an update isn't urgent, so if it suspends, React keeps the old screen until the new one is ready. You met startTransition in Optimistic UI, and the Transitions lesson covers it in depth. Here is the same page with one:

1import { Suspense, useState, useTransition } from "react";2import Details from "./Details.jsx";3import Reviews from "./Reviews.jsx";4 5export default function ProductPage() {6  const [productId, setProductId] = useState("tea");7  const [isPending, startTransition] = useTransition();8 9  function pick(id) {10    startTransition(() => {11      setProductId(id);12    });13  }14 15  return (16    <>17      <button onClick={() => pick("tea")}>Tea</button>18      <button onClick={() => pick("cake")}>Cake</button>19      <Suspense fallback={<p>Loading the product…</p>}>20        <div style={{ opacity: isPending ? 0.5 : 1 }}>21          <Details productId={productId} />22          <Reviews productId={productId} />23        </div>24      </Suspense>25    </>26  );27}

Line 7 calls useTransition, which gives two things: isPending, which is true while a transition waits, and startTransition. On lines 9 to 13, pick sets the product inside startTransition. Click Cake: tea stays on the screen, faded by line 20 while isPending is true, until cake's details and reviews are both ready, 1.2 seconds later. Then cake replaces it in one step.

How to read the table: each row is one question, answered for a plain update and for a transition.

A transition only keeps content that is already showing. A boundary that appears for the first time still shows its fallback, even in a transition, because there's nothing old to keep. Routers in frameworks start every navigation as a transition for you.

Load a component's code when it's needed

Code can make a component wait too. A bundler, like Vite, puts everything an app imports into files the browser downloads before it shows anything. A big component that few people open, like a brewing guide, makes everyone wait for it. lazy from React, together with a dynamic import, moves it into a file of its own, which the browser downloads the first time the component renders:

1import { Suspense, lazy, useState } from "react";2 3const BrewingGuide = lazy(() => slowDownload(import("./BrewingGuide.jsx")));4 5// Pretends the file takes a second to download.6function slowDownload(file) {7  console.log("Download BrewingGuide.jsx");8  return new Promise((resolve) => setTimeout(() => resolve(file), 1000));9}10 11export default function ProductPage() {12  const [open, setOpen] = useState(false);13  return (14    <>15      <h2>Green tea</h2>16      <button onClick={() => setOpen(!open)}>{open ? "Hide" : "Show"} the brewing guide</button>17      {open && (18        <Suspense fallback={<p>Loading the guide…</p>}>19          <BrewingGuide />20        </Suspense>21      )}22    </>23  );24}

Line 3 calls lazy at the top level of the file, with a function that returns the import() promise. The file it imports must export the component as its default export, as the BrewingGuide.jsx tab does. The examples here load their files at once, so slowDownload on lines 6 to 9 adds a second, like a slow network. Line 19 renders BrewingGuide like any component, inside the boundary on lines 18 to 20.

Click Show the brewing guide: Loading the guide… for a second, then the table. The console shows Download BrewingGuide.jsx and BrewingGuide.jsx runs (line 1 of the BrewingGuide.jsx tab) only after you click: before that, the file wasn't loaded at all. Click Hide, then Show again: the guide appears at once, because lazy keeps the component it loaded, so it doesn't suspend again.

Where you call lazy matters. This is wrong on purpose:

export default function ProductPage() {
  // Wrong: a new BrewingGuide component on every render.
  const BrewingGuide = lazy(() => import("./BrewingGuide.jsx"));
  // …
}

Line 3 runs on every render, so every render makes a new BrewingGuide component. React sees a different component each time, so it throws the old one away, with its state, and suspends again. Declare lazy components at the top level of a module, once.

A product page with planned loading states

Here is everything together: the details first, then the reviews in their own boundary, product switches in a transition, and a brewing guide whose code loads when it's opened.

1import { Suspense, lazy, useState, useTransition } from "react";2import Details from "./Details.jsx";3import Reviews from "./Reviews.jsx";4 5const BrewingGuide = lazy(() => import("./BrewingGuide.jsx"));6 7export default function ProductPage() {8  const [productId, setProductId] = useState("tea");9  const [guideOpen, setGuideOpen] = useState(false);10  const [isPending, startTransition] = useTransition();11 12  function pick(id) {13    startTransition(() => setProductId(id));14  }15 16  return (17    <>18      <nav>19        <button onClick={() => pick("tea")}>Tea</button>20        <button onClick={() => pick("cake")}>Cake</button>21        <button onClick={() => setGuideOpen(!guideOpen)}>Brewing guide</button>22      </nav>23      <Suspense fallback={<p>Loading the product…</p>}>24        <main style={{ opacity: isPending ? 0.5 : 1 }}>25          <Details productId={productId} />26          <Suspense fallback={<p>Loading reviews…</p>}>27            <Reviews productId={productId} />28          </Suspense>29        </main>30      </Suspense>31      {guideOpen && (32        <Suspense fallback={<p>Loading the guide…</p>}>33          <BrewingGuide />34        </Suspense>35      )}36    </>37  );38}

Line 5 declares the lazy guide at the top level. Lines 12 to 14 switch products in a transition. The outer boundary on lines 23 to 30 waits for the details, the inner one on lines 26 to 28 for the reviews, and the guide has its own boundary on lines 32 to 34, so opening it never hides the product.

Press Run again: Loading the product…, then the heading at 0.6 seconds with Loading reviews…, then the reviews at 1.5. Click Cake: tea stays, faded, and cake appears with its review 1.2 seconds later. In a transition React doesn't hide the reviews either, because they're already showing, so the switch waits for the slower part, the reviews. Click Brewing guide: its file loads quickly here, with no slowDownload, so you may only glimpse its fallback.

Common mix-ups

• "Suspense shows its fallback while my effect fetches." No. The component rendered fine, so nothing suspended. Suspense only sees components that suspend while rendering: use with a cached promise, lazy, and Suspense-enabled frameworks.
• "use can read any promise, even one made while rendering." No. A new promise on every render means every render waits again. The promise has to come from a cache that returns the same one.
• "A boundary waits only for the component that suspended." No. It waits for everything inside it that isn't inside a nested boundary, and shows it all together.
• "More boundaries always make a better page." No. Each boundary is a separate loading state. Too many make the page jump; put them where a person expects one.
• "React 19 never renders the siblings of a component that suspends." No. It shows the fallback first, then renders them in a pre-warm, so their loading still starts early.
• "A transition makes the data load faster." No. The data takes just as long. A transition only keeps what's already on the screen, instead of a fallback, until the new content is ready.
• "lazy can go anywhere, even inside a component." No. Inside a component it makes a new component on every render, which loses its state and suspends again. Call it once, at the top level.
• "Suspense shows the fallback when the data fails to load too." No. A promise that rejects makes use throw its error, which goes to the nearest error boundary. The Error boundaries lesson covers them.

Practice exercises

Each exercise uses the same pretend server: in its data.js tab, tea's details take 0.6 seconds and its reviews 1.5. Change the code with Edit & run, and press Run again to load from an empty cache.

import { Suspense } from "react";
import Details from "./Details.jsx";
import Reviews from "./Reviews.jsx";

export default function ProductPage() {
  return (
    <Suspense fallback={<p>Loading the product…</p>}>
      <Details productId="tea" />
      <Reviews productId="tea" />
    </Suspense>
  );
}

1import { Suspense } from "react";2import Details from "./Details.jsx";3import Reviews from "./Reviews.jsx";4 5export default function ProductPage() {6  return (7    <Suspense fallback={<p>Loading the product…</p>}>8      <Details productId="tea" />9      <Reviews productId="tea" />10    </Suspense>11  );12}

1import Reviews from "./Reviews.jsx";2 3export default function ProductPage() {4  return (5    <>6      <h2>Green tea</h2>7      <Reviews productId="tea" />8    </>9  );10}

1import { Suspense } from "react";2import Reviews from "./Reviews.jsx";3 4export default function ProductPage() {5  return (6    <>7      <h2>Green tea</h2>8      <Suspense fallback={<p>Loading reviews…</p>}>9        <Reviews productId="tea" />10      </Suspense>11    </>12  );13}

1import { Suspense } from "react";2import Details from "./Details.jsx";3import Reviews from "./Reviews.jsx";4 5export default function ProductPage() {6  return (7    <Suspense fallback={<p>Loading the product…</p>}>8      <Details productId="tea" />9      <Reviews productId="tea" />10    </Suspense>11  );12}

1import { Suspense } from "react";2import Details from "./Details.jsx";3import Reviews from "./Reviews.jsx";4 5export default function ProductPage() {6  return (7    <Suspense fallback={<p>Loading the product…</p>}>8      <Details productId="tea" />9      <Suspense fallback={<p>Loading reviews…</p>}>10        <Reviews productId="tea" />11      </Suspense>12    </Suspense>13  );14}

1import { useState } from "react";2import BrewingGuide from "./BrewingGuide.jsx";3 4export default function ProductPage() {5  const [open, setOpen] = useState(false);6  return (7    <>8      <h2>Green tea</h2>9      <button onClick={() => setOpen(!open)}>{open ? "Hide" : "Show"} the brewing guide</button>10      {open && <BrewingGuide />}11    </>12  );13}

1import { Suspense, lazy, useState } from "react";2 3const BrewingGuide = lazy(() => import("./BrewingGuide.jsx"));4 5export default function ProductPage() {6  const [open, setOpen] = useState(false);7  return (8    <>9      <h2>Green tea</h2>10      <button onClick={() => setOpen(!open)}>{open ? "Hide" : "Show"} the brewing guide</button>11      {open && (12        <Suspense fallback={<p>Loading the guide…</p>}>13          <BrewingGuide />14        </Suspense>15      )}16    </>17  );18}

1import { Suspense, use } from "react";2import { fetchData } from "./data.js";3 4function Reviews() {5  const reviews = use(fetchData("/reviews/tea").then((list) => list.slice(0, 1)));6  return <p>Top review: {reviews[0]}</p>;7}8 9export default function ProductPage() {10  return (11    <>12      <h2>Green tea</h2>13      <Suspense fallback={<p>Loading reviews…</p>}>14        <Reviews />15      </Suspense>16    </>17  );18}

1import { Suspense, use } from "react";2import { fetchData } from "./data.js";3 4function Reviews() {5  const reviews = use(fetchData("/reviews/tea"));6  return <p>Top review: {reviews[0]}</p>;7}8 9export default function ProductPage() {10  return (11    <>12      <h2>Green tea</h2>13      <Suspense fallback={<p>Loading reviews…</p>}>14        <Reviews />15      </Suspense>16    </>17  );18}

1import { Suspense, useState } from "react";2import Details from "./Details.jsx";3import Reviews from "./Reviews.jsx";4 5export default function ProductTabs() {6  const [tab, setTab] = useState("details");7  return (8    <>9      <button onClick={() => setTab("details")}>Details</button>10      <button onClick={() => setTab("reviews")}>Reviews</button>11      <Suspense fallback={<p>Loading…</p>}>12        {tab === "details" ? <Details productId="tea" /> : <Reviews productId="tea" />}13      </Suspense>14    </>15  );16}

1import { Suspense, useState, useTransition } from "react";2import Details from "./Details.jsx";3import Reviews from "./Reviews.jsx";4 5export default function ProductTabs() {6  const [tab, setTab] = useState("details");7  const [isPending, startTransition] = useTransition();8 9  function show(next) {10    startTransition(() => {11      setTab(next);12    });13  }14 15  return (16    <>17      <button onClick={() => show("details")}>Details</button>18      <button onClick={() => show("reviews")}>Reviews</button>19      <Suspense fallback={<p>Loading…</p>}>20        <div style={{ opacity: isPending ? 0.5 : 1 }}>21          {tab === "details" ? <Details productId="tea" /> : <Reviews productId="tea" />}22        </div>23      </Suspense>24    </>25  );26}

Check your understanding

For each question, find the boundary each component is in, then ask what that boundary is still waiting for.

Key takeaways

• <Suspense fallback={…}> shows its fallback while anything inside it is waiting, and its children once all of them are ready.
• Components suspend when they read an unresolved, cached promise with use, render a lazy component that hasn't loaded, or read framework data. Requests in effects don't suspend.
• One boundary reveals its content together. Nested boundaries reveal the page in steps, each waiting only for its own part.
• React 19 shows the fallback as soon as something suspends, then pre-warms the siblings so their loading starts early.
• A plain update that suspends hides content already on screen. A transition keeps it until the new content is ready.
• lazy and import() load a component's code the first time it renders. Declare it once, at the top level.

Coming next: The use API. It covers use in full: reading promises and context, calling it inside conditions, and where its promises should come from.