Suspense Patterns — React Deep Dive

the throw-promise mechanism

A component throws a promise during render when the data it needs isn't ready. React catches the thrown promise, walks UP the tree to the nearest <Suspense>, and renders its fallback instead. When the promise resolves, React re-renders the suspended subtree — now the data is there, so read() returns it and the real UI paints. No isLoading flags, no useEffect+setState, no race conditions: the loading state is a property of the tree, not a field you manage.

API	what it suspends on	resolves when
`React.lazy(() => import())`	a component module	the dynamic `import()` promise settles
`use(promise)` (React 19)	a Promise (or Context)	the awaited promise resolves
`resource.read()` (this demo)	any cached promise	the wrapper flips status to `'success'`
`<Suspense fallback>`	— (the catcher, not the thrower)	the nearest child stops suspending

1 · the resource cache you write (edit me)

var Suspense = React.Suspense;
var fetchSeq = 0;

// Simulated network: resolves after 600ms with a labeled string.
function fetchData() {
  fetchSeq = fetchSeq + 1;
  var n = fetchSeq;
  var label = n === 1 ? 'Hello Suspense!' : ('Reload #' + n + ' OK');
  return new Promise(function (resolve) {
    setTimeout(function () { resolve(label); }, 600);
  });
}

// The resource cache: wraps a promise so read() THROWS it while pending.
// React catches the thrown promise and shows the Suspense fallback.
function createResource(promise) {
  var status = 'pending';
  var result;
  var suspender = promise.then(
    function (r) { status = 'success'; result = r; },
    function (e) { status = 'error'; result = e; }
  );
  return {
    read: function () {
      if (status === 'pending') throw suspender;  // <-- the throw
      if (status === 'error') throw result;       // <-- errors bypass Suspense to ErrorBoundary
      return result;
    }
  };
}

// Reads the data. While pending, resource.read() throws -> Suspense catches.
function DataViewer(props) {
  var data = props.resource.read();
  return (
    <div data-testid="data" className="p-4 bg-[#0d1117] rounded border border-[#30363d] text-[#e6edf3]">
      Loaded: {data}
    </div>
  );
}

function App() {
  // Lazy initializer: create the resource ONCE on mount (no refetch on re-render).
  var state = React.useState(function () {
    return createResource(fetchData());
  });
  var resource = state[0];
  var setResource = state[1];

  function refetch() {
    // New resource -> new promise -> re-suspend -> fallback -> resolve.
    setResource(createResource(fetchData()));
  }

  return (
    <div className="max-w-md mx-auto">
      <Suspense fallback={
        <div data-testid="loading" className="p-4 bg-[#0d1117] rounded border border-[#30363d] text-[#8b949e]">
          Loading…
        </div>
      }>
        <DataViewer resource={resource} />
      </Suspense>
      <button
        data-testid="refetch"
        className="mt-3 px-4 py-2 bg-[#61dafb] text-[#0d1117] rounded font-bold text-sm"
        onClick={refetch}
      >
        Refetch
      </button>
    </div>
  );
}

createRoot(document.getElementById('root')).render(<App/>);

2 · Babel compiles JSX → element tree

<Suspense fallback={...}> becomes React.createElement(Suspense, {fallback: ...}). The thrown promise is invisible at the JSX level — it lives inside resource.read(), which Babel leaves untouched as a plain function call.

// (hit "compile & render" to see Babel's output)

3 · live React (the throw-promise round-trip, proven)

On mount, DataViewer calls resource.read() — the promise is pending, so it throws. Suspense catches it and renders the Loading… fallback. ~600ms later the promise resolves, React retries, and Loaded: Hello Suspense! paints. Click Refetch to swap in a fresh resource and watch the round-trip again. The gold-check automates all of this.

state: — · gold: fallback → "Hello Suspense!" → Refetch → "Reload #2 OK"

intent → Suspense pattern

intent	pattern	why
lazy-load a component	`const C = lazy(() => import('./C'))` `<Suspense fallback={...}><C/></Suspense>`	suspends until the chunk downloads; no waterfall on route change
read a promise during render	`const data = use(promise)`	React 19 native; throws the promise, Suspense catches — no manual cache needed if the promise is cached upstream
avoid refetch on every render	cache the promise (`useState(() => createResource(fetch()))`)	Suspense re-renders the subtree; an uncached promise re-suspends forever
isolate loading regions	nest `<Suspense>`	the nearest ancestor's fallback wins; outer content stays interactive while a child loads
handle fetch errors	wrap `<ErrorBoundary>` around `<Suspense>`	a thrown error from a suspended component bypasses Suspense and bubbles to the boundary
keep showing old data while refetching	`useTransition` + `<Suspense>`	the transition holds the old UI until the new resource resolves; fallback only on first load