Course contentsShow
← React
Lesson 1360 of 2,39634. Suspense FundamentalsFree lesson

The 'Suspend' Contract: Throwing Promises

How Suspense-enabled libraries throw promises during render to signal loading states to React.

The 'Suspend' Contract: Throwing Promises

What you'll learn: How React detects that data isn't ready yet by catching thrown promises during render.

The "Throwing a Promise" Mechanism

When you've been using Suspense for code splitting with React.lazy(), you've been benefiting from this pattern without seeing it. Now let's understand the underlying contract.

Suspense-enabled libraries signal "not ready" by literally throwing a promise during render. Yes, you read that right—they throw a promise object, not an error. When React catches this thrown promise, it knows to:

  1. Stop rendering that component tree
  2. Show the nearest Suspense boundary's fallback
  3. Wait for the thrown promise to resolve
  4. Retry rendering once the data arrives

The Mental Model

Think of it like a restaurant kitchen: when a chef (your component) realizes an ingredient isn't ready, they don't just stand there waiting. They throw the order ticket back out to the expo station (Suspense boundary), which displays "Order in Progress" to the customer. When the ingredient arrives, the ticket comes back and cooking resumes.

Why This Works

This isn't a hack—it's an intentional design pattern. React's reconciler is built to catch these thrown promises and treat them differently from errors. The promise itself becomes the signal: "I need this data; wake me when it resolves."

You won't write this code yourself for data fetching (libraries like Relay, SWR, or TanStack Query handle it), but understanding the contract explains why Suspense feels "magical"—it's actually a clever use of JavaScript's exception mechanism.

Key Takeaway: Suspense-enabled libraries throw promises during render to communicate async dependencies to React, which pauses rendering and shows fallback UI until the promise resolves.