Skip to content

Suspense and the use Hook: Rendering as If the Data Were Already There

Instead of managing a loading state in every component, Suspense lets you describe in a single place in the tree what appears while waiting – and the use hook lets the component below render as if the data had long arrived.

≈ 10 min readSoftwareFrontendReact

Suspense and the use Hook: Rendering as If the Data Were Already There

If you program waiting separately into every component, you pay for it in the UI: three data-loading components side by side mean three spinners that flash up independently and disappear again at three different times. The page twitches while it builds up, and each of these components drags the same three cases around with it – loading, error, data. Somewhere in each one there’s if (isLoading) return <Spinner /> and below it if (error) return <ErrorMessage />.

Moving to TanStack Query or SWR doesn’t change that either. In the article on client state and server cache, I showed how server data moves out of the patchwork of useState and useEffect and into a cache library – the loading state doesn’t move along with it; it stays in every component that needs data. React 19 starts somewhere else, namely with the question of where in the tree the waiting happens at all. Suspense turns it around: waiting no longer belongs in each individual component but in one place above them. And the component below may act as if the data were already there.

Editorial note (July 2026): Suspense doesn’t react to arbitrary data loading in an effect or event handler. For data, the flow described here works with Suspense-enabled frameworks and libraries or when reading a stable, cached promise with use. A freely usable, stable React API for building your own Suspense data sources is still not documented.

The loading state leaves the component#

Let’s first look at what it looks like without Suspense. A component that displays a list of invoices carries the three states itself:

function InvoiceList() {
  const { data, isLoading, error } = useInvoices();

  if (isLoading) return <Spinner />;
  if (error) return <ErrorMessage error={error} />;

  return (
    <ul>
      {data.map((invoice) => (
        <li key={invoice.id}>{invoice.title}</li>
      ))}
    </ul>
  );
}

That’s not terrible, but it repeats itself. Every data-loading component looks like this, each has its own Spinner, its own error handling. And when three such components sit side by side, three spinners flash up independently and disappear at different times – a restless picture.

Suspense offers a different idea. You wrap part of the tree once with <Suspense> and say: everything in here that is still waiting for data should show this fallback until then.

<Suspense fallback={<Spinner />}>
  <InvoiceList />
</Suspense>

The InvoiceList itself no longer knows about a loading state. It requests the data, and if it isn’t there yet, React pauses the component and shows the fallback of the nearest enclosing <Suspense> component instead. The word for this is suspending: the component pauses in the middle of rendering until what was promised arrives. The fallback is no longer the component’s business but that of the <Suspense> above it.

The use hook reads a promise#

For a component to be able to suspend at all, it needs a way to “read” a promise that is still pending. That’s exactly what the use hook does, which is stable as of React 19. You pass it a promise, and it returns the resolved value – or interrupts rendering if the value isn’t there yet.

import { use } from "react";

function InvoiceList({ invoicesPromise }) {
  const invoices = use(invoicesPromise);

  return (
    <ul>
      {invoices.map((invoice) => (
        <li key={invoice.id}>{invoice.title}</li>
      ))}
    </ul>
  );
}

You read this line almost like synchronous code: const invoices = use(invoicesPromise), and after that invoices is simply available. The component sees nothing of the time in between, while the promise is still pending. If the promise isn’t fulfilled yet, use suspends the component, React pauses and shows the fallback of the enclosing <Suspense> component. As soon as the promise is fulfilled, React renders the component again, this time with the value in hand.

By the way, besides promises, use also accepts a context and replaces useContext in that role. But the interesting case for this article is the promise, because that’s where the interplay with Suspense hinges.

Why use may be called conditionally#

It’s worth taking a quick look at a peculiarity that at first glance looks like breaking the rules. For all other hooks, an iron rule applies: they have to be at the top level of the component, always in the same order, never inside a condition or loop. The reason is that React maps the hooks per render by their call order – if the order gets mixed up, React confuses the states.

use is explicitly exempt from this rule. You may call it inside an if condition, in a loop, after an early return:

function Message({ show, messagePromise }) {
  if (show) {
    const message = use(messagePromise);
    return <p>{message}</p>;
  }
  return null;
}

That’s more than a convenience. use doesn’t store any state itself that would have to be mapped to a component through a fixed call order – it only reads a value from an object you hand it. That’s why it can sit where it belongs in terms of content, instead of being forced to the top of the component. You read a promise exactly when you actually need its value.

The error boundary handles errors#

That leaves the third state from above: the error. If the promise isn’t fulfilled but rejected, use throws that error during rendering. And a thrown error ends up at the nearest error boundary – the same mechanism React has always used to catch render errors.

<ErrorBoundary fallback={<ErrorMessage />}>
  <Suspense fallback={<Spinner />}>
    <InvoiceList invoicesPromise={invoicesPromise} />
  </Suspense>
</ErrorBoundary>

With that, the math works out. The three states that each component used to manage itself – loading, error, data – have become two safety nets in the tree plus the pure success case in the component. The <Suspense> takes care of waiting, the <ErrorBoundary> of failing, and the component itself only renders the case it’s actually there for: the available data. The if (isLoading) and the if (error) are gone without replacement.

flowchart TB
  R["Component renders,<br/>calls use(promise)"] --> Q{"Promise state?"}
  Q -->|pending| S["suspends →<br/>Suspense shows fallback"]
  S -.->|promise fulfilled| R
  Q -->|fulfilled| OK["Content appears<br/>with the data"]
  Q -->|rejected| ERR["Error is thrown →<br/>ErrorBoundary catches it"]

At this point, an error boundary is still a class component, or you reach for a small package like react-error-boundary – there’s no built-in function variant in React 19 yet. But that doesn’t change the picture: conceptually, it’s the second safety net next to Suspense.

Staying honest: use isn’t a cache library#

Now comes the part that’s easy to skim over, because the examples above look so tidy. Where does the invoicesPromise actually come from? In the code snippets I passed it in as a prop and thereby postponed the question. But it’s the decisive one.

You might get the idea of simply creating the promise in the component:

function InvoiceList() {
  // Trap: creates a new promise on EVERY render
  const invoices = use(fetch("/api/invoices").then((r) => r.json()));
  // ...
}

That looks compact and is still wrong. Every render pass calls fetch again and creates a fresh promise. React sees a pending promise, suspends, re-renders after it resolves – and in doing so immediately creates the next new promise. You build yourself an infinite loop of loading. use caches nothing, it deduplicates nothing, it only reads what you give it.

For this to work, the promise has to come from outside rendering: from someone who creates it once, stores it under a key and returns the same promise on the next request. That’s exactly the bookkeeping – keys, age, deduplication, invalidation – that I described in the article on the server cache. use and Suspense don’t solve it; they presuppose it.

In practice, therefore, the same tools you already use deliver the promises. TanStack Query and SWR both have a Suspense mode: instead of returning isLoading and error, they suspend and throw in the error case, so that Suspense and the error boundary take over the states. Or a framework like Next.js creates the promises on the server and passes them in. The rule from the cache article applies unchanged: server data needs a cache with keys and invalidation. Suspense only changes how waiting for it feels in the tree – not the fact that someone has to run the cache.

Where the effort pays off#

If use doesn’t take the bookkeeping off your hands, why the whole rework? The gain lies elsewhere, namely in coordinating several data sources under a shared <Suspense>.

Imagine a profile page that loads user data, the latest posts and some statistics – three sources. Without Suspense, three spinners flash up independently and resolve at three different times; the page twitches as it builds up. If you put the three components under a shared <Suspense>, React waits until all three are ready and then shows the finished page in one piece. One fallback instead of three, one moment of appearing instead of three.

Just as often you want the opposite: not to wait for the slowest source, but to show the fast part right away. Then you nest several <Suspense> components. The user profile sits under an outer <Suspense> and appears early; the slow statistics get their own inner <Suspense> with their own fallback and slide in as soon as they’re there.

<Suspense fallback={<PageSkeleton />}>
  <UserProfile userPromise={userPromise} />
  <Suspense fallback={<StatsSkeleton />}>
    <Statistics statsPromise={statsPromise} />
  </Suspense>
</Suspense>

That’s how you describe a staggered appearance as structure in the tree, not as logic in the components. Where something appears and in what order, you can read from the nesting of the <Suspense> components – in one place, instead of scattered across a dozen isLoading checks. That’s the real gain: the loading UI lives where you think about layout, not once more in every component.

A second, less visible benefit is connected to this: Suspense counteracts loading waterfalls. A waterfall occurs when a component first loads, then renders, and a child inside it only then starts its own loading – the requests line up one after another even though they don’t depend on each other at all. Classic useEffect loading produces exactly this pattern almost by itself, because each component only fetches once it renders, and children only render once their parents have finished loading. If you instead pass the promises in from outside and start them early, the requests run in parallel, while use collects them again under a shared <Suspense>. The structure of waiting and the structure of loading no longer necessarily coincide.

A reload that leaves the old UI standing#

One more detail deserves a brief mention, because it quickly becomes important in practice. Suspense shows its fallback not only on the first load but also when the data under a <Suspense> changes – for example, when you switch from one invoice to the next and a new promise is created. Without precautions, the page then jumps back to the spinner, even though usable data was visible just a moment ago.

That’s exactly what useTransition and startTransition are for. If you mark the data change as a transition, React keeps the old UI standing and loads in the background instead of dropping straight into the fallback. Meanwhile, you can indicate that something is in progress – grayed out, with a subtle hint – without throwing away the content that’s already rendered. That deserves its own article; here it should just be clear that jumping hard back into the fallback isn’t mandatory.

What should stick#

Suspense and use don’t shift who fetches the data – that remains the job of a cache. They shift where waiting is described. Instead of programming three states into every component, you pull loading and errors together in two places in the tree – Suspense and the error boundary – and let the components below assume the success case. Each individual component gets smaller and more honest as a result: it acts as if the data were there, because a <Suspense> above it makes sure they are when the component’s turn comes.

When designing a page, that leaves one question: at which places in the tree may waiting happen, and what should be visible there in the meantime? The answer is a few <Suspense> components in the right places – and components that no longer need to know anything about waiting.

Further reading#

Revised and translated from German with the help of AI.