Suspense for data: the throw-a-promise contract, use(), and boundaries as UX design

The contract: suspend by throwing, resume by retrying

Why does this matter to you as an engineer? Because understanding the throw-and-retry contract is the only way to diagnose the two failure modes from the Hook — infinite loops and page-wide blanks — and to place boundaries intentionally rather than by cargo-cult.

Mechanically, Suspense is an exception protocol. When a component cannot render because its data is not ready, it throws a thenable (promise-like object). React catches it while unwinding the render — remember, render is pure and discardable, so abandoning the attempt is free — walks up to the nearest <Suspense> boundary, and commits that boundary’s fallback instead of the subtree. React then subscribes to the thrown promise; when it resolves, React retries rendering the subtree from scratch. On the retry, the component runs again, the data source now has a value, the read returns synchronously, and the real UI commits. The component itself contains no loading branch — “not ready” is not a state it models, it is an exception it throws.

use() is the sanctioned read primitive: const user = use(userPromise) returns the resolved value, throws the promise to suspend if pending, and throws the rejection reason if rejected. Unlike hooks, use may be called inside conditionals and loops — it is a read, not a state registration. The promise itself should be created elsewhere (a parent, a router loader, a cache) and passed down or looked up; the component’s job is only to read.

const cache = new Map();
function fetchUser(id) {              // identity: same id → same promise
  if (!cache.has(id)) {
    cache.set(id, fetch(`/api/users/${id}`).then((r) => {
      if (!r.ok) throw new Error(`HTTP ${r.status}`);
      return r.json();
    }));
  }
  return cache.get(id);
}

function Profile({ id }) {
  const user = use(fetchUser(id));    // suspends while pending
  return <h1>{user.name}</h1>;
}

// <ErrorBoundary fallback={<Oops />}>
//   <Suspense fallback={<Skeleton />}>
//     <Profile id={42} />
//   </Suspense>
// </ErrorBoundary>

Why raw fetch in render loops forever

Here is the trap from the Hook, mechanically. Render is pure and re-runnable: React may call your component many times, and each suspension discards the attempt entirely. If the component body itself creates the promise — use(fetch(url)) — then the retry after resolution runs the body again and creates a brand-new, pending promise. The one that resolved is gone with the discarded render; the new one suspends; React subscribes, it resolves, retry, new promise, suspend. The loop never converges, and every iteration fires a real network request. The fix is identity: some store outside render must return the same promise for the same logical request, so the retry’s use() call receives the promise that already resolved and reads through synchronously. That store is a cache — a Map keyed by request parameters in the toy version, a query library or framework loader in production. This is the structural reason React’s docs say Suspense-enabled data fetching is meant to be provided by frameworks and caching libraries rather than hand-rolled: the contract is easy, the cache (invalidation, eviction, deduplication) is the actual product.

Boundaries are UX design, errors are the boundary’s twin

Where you place <Suspense> decides where spinners appear — that is a design decision expressed in component structure. One boundary at the page root means the entire page is all-or-nothing: simplest, but any slow widget blanks everything (the Hook’s second incident). A boundary per widget means each section reveals independently — fast widgets appear immediately, slow ones show local skeletons — at the cost of “popcorn UI”, content popping in random order and shifting layout. The senior pattern is deliberate grouping: wrap the parts users perceive as one unit (header + summary) in one boundary so they appear together, give long-tail sections (analytics, recommendations) their own. Nested boundaries compose: a suspension is caught by the nearest ancestor boundary, so inner boundaries scope inner loading states while the outer one covers initial mount. To control reveal ordering — top-to-bottom instead of whoever-resolves-first — React’s experimental SuspenseList coordinated multiple boundaries; until it stabilizes, the same effect comes from boundary structure or from awaiting combined promises higher up.

Rejection is the mirrored path: when the awaited promise rejects, the retry throws the rejection during render, and that exception travels to the nearest error boundary — not the Suspense boundary. A production-grade tree therefore pairs them: ErrorBoundary outside, Suspense inside, per region. Tradeoff to keep honest: fallbacks replace content. For updates after the initial load, replacing live data with a spinner is often worse than showing slightly stale data — which is why startTransition exists: updates marked as transitions do not trigger an already-revealed boundary’s fallback; React keeps the old UI while the new tree suspends in the background.