Suspense boundaries
Slap yourself if
You think Suspense is just a loading spinner with better ergonomics.
Why this exists
Suspense boundaries exist because rendering can no longer assume data, code, and state are synchronously available. Instead of blocking the entire tree, the renderer needs explicit cut points where it’s allowed to pause, defer, or replace UI.
Mental model
A Suspense boundary is not a loading state — it’s a fault line. It defines where rendering is allowed to break, recover, and resume without corrupting the rest of the UI.
- Rendering proceeds until a suspended read is encountered.
- The nearest Suspense boundary intercepts the suspension.
- That subtree is replaced with fallback UI.
- Rendering continues elsewhere using a consistent snapshot.
- The suspended work retries later with new data.
- Over-scoping boundaries so large UI chunks disappear.
- Under-scoping boundaries, causing waterfalls.
- Treating Suspense as a data-fetching abstraction.
- Assuming fallbacks are just visual placeholders.
A Suspense boundary defines where the renderer is allowed to pause and substitute UI when data or code isn’t ready, preserving consistency while enabling concurrent rendering.
- Single global Suspense boundary
- Fallbacks that don’t match layout or intent
- Using Suspense without understanding retry semantics
- Expecting Suspense to fix architectural waterfalls
Deep dive
Requires Pro
Premium deep dives include more internals, more scars.