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.
const user = use(getUser(id)); // getUser returns a cached promise
Try it
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.
Syntax
<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, orcachein 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
startTransitionkeeps 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
usecalls 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.