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

Suspense Boundaries and Error Boundaries Together

Combining Suspense for loading states with Error Boundaries for failures at matching levels.

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.