Suspense Boundaries and Error Boundaries Together
You'll learn how to combine Suspense and Error Boundaries at the same component tree level to handle both loading and failure states gracefully.
Two Boundaries, One Job
Think of Suspense and Error Boundaries as sibling safety nets beneath a trapeze act. Suspense catches the "I'm not ready yet" scenario (the performer is still climbing the ladder), while Error Boundaries catch the "something went wrong" scenario (the performer slipped). You want both nets in place at the same level to cover all possible outcomes.
The Pattern: Wrap Together
The most robust pattern is wrapping your Suspense boundary inside an Error Boundary:
<ErrorBoundary fallback={<ErrorMessage />}>
<Suspense fallback={<LoadingSpinner />}>
<ComponentThatMightSuspendOrFail />
</Suspense>
</ErrorBoundary>
This placement ensures:
- While loading: Suspense shows the spinner
- If data fetch fails: Error Boundary catches the error
- When successful: Neither boundary activates, content renders normally
Why This Matters
Without both boundaries at matching levels, you get incomplete coverage. A Suspense boundary alone can't catch errors that occur during data fetching. An Error Boundary alone can't handle the "still loading" state that causes components to suspend.
Together, they create a complete UI state machine: loading → success or error.
Matching Granularity
Apply the same granularity thinking from your previous lessons. If you have nested Suspense boundaries for fine-grained loading, add Error Boundaries at those same levels for fine-grained error handling. This keeps each section of your UI independently resilient.
Key Takeaway: Always pair Suspense boundaries with Error Boundaries at the same tree level—Suspense handles "not ready yet," Error Boundary handles "failed," and together they create complete async state management.