How it works
Implementation details of React 19.3.1:
use throws. When the promise is pending, use attaches handlers that write status and value (or reason) onto the promise itself, then throws a sentinel, SuspenseException. Its message, "Suspense Exception: This is not a real error!", is what you see if you catch it in a try/catch. lazy throws the same way while its module loads.
- The work loop unwinds.
handleThrow records why the render stopped. throwException finds the nearest boundary from the suspense handler stack, marks it to capture, and attaches a listener to the promise. Rendering resumes at that boundary, now rendering its fallback.
- Siblings are skipped, then pre-rendered. On a normal render React skips the suspended component's siblings and schedules a retry of the boundary straight away. That retry runs as a pre-render: it renders every sibling without committing, which is when
B logged in the example.
- The retry commits. When the promise settles, its listener schedules a render on a retry lane. The component calls
use again; the promise's status is now fulfilled, so use returns value synchronously.
- Throttling.
globalMostRecentFallbackTime is set whenever a commit switches a boundary between fallback and content. A render made only of retries that finishes earlier than 300 ms after that is held back until 300 ms have passed:
// Simplified from ReactFiberWorkLoop.js
const FALLBACK_THROTTLE_MS = 300;
// … when a concurrent render finishes:
if (includesOnlyRetries(lanes) && (alwaysThrottleRetries || exitStatus === RootSuspended)) {
const msUntilTimeout = globalMostRecentFallbackTime + FALLBACK_THROTTLE_MS - now();
if (msUntilTimeout > 10) { /* schedule the commit for later */ }
}
Legacy: before React 19.0, React rendered all the siblings first and committed the fallback afterwards, so a slow sibling delayed the loading state.
Edge cases
Measured in Chrome 156 and Firefox 159, development and production. The fallback committed at 1–7 ms each time:
The second case shows the window restarting: the outer reveal itself counts as a switch, so the inner content waited another 300 ms. A single boundary whose data arrived at 200 ms was revealed at 303–310 ms too.
Re-suspending visible content. Here an urgent flushSync update made a mounted component read a new pending promise:
<p id="item" style="display: none !important;">item 1</p><i>loading</i>
That's the container right after the update. The old DOM stayed, hidden, and its state was kept; the layout effect's cleanup ran, but the useEffect stayed set up until the dependency changed with the new data. Layout effects re-ran on reveal, 300 ms after the fallback appeared.
Real-world scenario
A dashboard with a header, a sidebar and three charts. One boundary around the content area makes the whole area flash a spinner whenever any chart loads. One boundary per chart gives three independent skeletons, and the throttle merges charts that finish within 300 ms of each other into one reveal. Nest: a page-level fallback while the shell's data loads, then per-chart fallbacks. When the user switches dates, the charts would fall back to skeletons again; making that update a Transition keeps the old charts visible instead.
Trade-offs
Suspense moves loading states out of components: a component reads data as if it were there, and the tree decides where waiting is shown. In return, the data source must cache promises (a framework, a library, or your own cache), a never-mounted component can't keep state across a retry, and the fallback granularity is whatever the boundaries say, so a misplaced boundary hides more UI than intended. The throttle trades up to 300 ms of extra latency for fewer layout jumps.