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:
- Stop rendering that component tree
- Show the nearest Suspense boundary's
fallback - Wait for the thrown promise to resolve
- 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.