Skip to content
Tutorials Center
My learning

Topics

React Reference ยท Performance and Concurrency Hooks

React use with Suspense

How to unwrap promises with use() inside Suspense: cache one promise per key, show fallbacks, keep old content with transitions, and handle rejections.

use turns a promise into a value during render. While the promise is pending, the component suspends: React stops rendering it and shows the fallback of the nearest <Suspense> boundary. When the promise resolves, React tries again and this time use returns the value. If the promise rejects, the error is thrown and an error boundary handles it.

The one rule that makes this work in the browser: the promise must have the same identity on every render. The practical way is a small cache keyed by the request, so that asking for the same thing twice returns the same promise.

JSX
const user = use(getUser(id)); // getUser returns a cached promise

Try it

A cached promise per user id

The first load shows the fallback. Afterwards the transition keeps the old card on screen (dimmed) while the next user loads. Click a user a second time: no new fetch, because the cached promise is already resolved.

Catching a rejected promise

Syntax

JSX
<ErrorBoundary>
  <Suspense fallback={<Spinner />}>
    <Child />   {/* calls use(promise) */}
  </Suspense>
</ErrorBoundary>
Piece Role
use(promise) Suspends while pending; returns the value when fulfilled; throws the reason when rejected.
<Suspense fallback> Shows fallback for any suspended descendant, then swaps in the real content.
Error boundary Class component with getDerivedStateFromError that renders an error message.
useTransition / startTransition Keeps already visible content on screen instead of showing the fallback again.

Errors / edge cases: a promise created during a Client Component's render makes React re-create it on every retry, leading to an endless loading state (React warns in development).

Usage notes

  • Cache by key. Store promises in a Map, a module-level object, a data library, or cache in Server Components. Clear or replace an entry to refetch.
  • Boundary placement decides the loading experience. One boundary around a page shows one spinner; several smaller ones reveal parts independently. See Nested Suspense boundaries.
  • Transitions avoid flicker. Updating the key inside startTransition keeps the current UI, whereas a plain update replaces it with the fallback.
  • Mark rejected promises as handled (as failing.catch(() => {}) above) if the promise exists before anything reads it, to avoid "unhandled rejection" noise.
  • Do not fetch in render yourself. Starting a request inside the component without a cache runs it on every retry. Start fetches in event handlers, loaders or Server Components, and pass the promise down.
  • Waterfalls. Sequential use calls in one component wait one after another. Start independent promises first and read them afterwards.
  • Server rendering: with streaming APIs a suspended boundary sends its fallback first, then the real HTML when ready.