Skip to main content

Where to Place Error Boundaries #140

📖 Introduction​

Now that we've successfully built a Reusable Error Boundary Component, the next critical question is: where should you place these Error Boundaries within your React application? The strategic placement of Error Boundaries is key to maximizing their effectiveness. Placing them too high might mean a large part of your UI is replaced on any error, while placing them too granularly might be overly verbose. This article discusses common strategies and considerations for deciding where to wrap your components.

📚 Prerequisites​

Before we begin, ensure you have:

  • A reusable ErrorBoundary component (as built in Articles 138-139).
  • A good understanding of your application's component structure and which parts are critical versus non-critical.

🎯 Article Outline: What You'll Master​

In this article, you will learn:

  • ✅ The "Granularity" Trade-off: Balancing safety with user experience.
  • ✅ Top-Level Error Boundary: Protecting the entire application.
  • ✅ Route-Level Error Boundaries: Isolating errors to specific pages or views.
  • ✅ Widget/Component-Level Boundaries: Protecting individual, potentially risky UI sections.
  • ✅ Boundaries Around Third-Party Components: Shielding your app from external library errors.
  • ✅ Contextual Fallbacks: Tailoring fallback UIs based on where the Error Boundary is placed.
  • ✅ General Best Practices and Considerations.

🧠 Section 1: The Granularity Trade-off​

The core decision when placing Error Boundaries is about granularity: how large or small a section of your UI should an individual Error Boundary protect?

  • Too Coarse (e.g., one boundary for the whole app):
    • Pros: Simple to implement; ensures some fallback is always shown if anything goes wrong.
    • Cons: If an error occurs in a small, non-critical widget, the entire application UI might be replaced by the fallback. This is often a poor user experience as much of the app might still be usable.
  • Too Fine (e.g., wrapping every single component):
    • Pros: Highly isolated errors; only the tiny component that failed shows a fallback.
    • Cons: Can become extremely verbose and clutter your component tree. Performance overhead might also be a concern if overdone, though typically minor for Error Boundaries themselves. More importantly, it might lead to a "speckled" UI of many tiny error messages if multiple small components fail.
  • Just Right (Strategic Placement):
    • The goal is to find a balance. Wrap sections of your application that make sense as independent units. If one unit fails, the others can often continue to function.

Think about your application in terms of major sections or features. Which parts can operate independently if another part fails?

💻 Section 2: Common Placement Strategies​

Here are common places where Error Boundaries are strategically useful:

2.1 - Top-Level (App Root) Error Boundary​

It's generally a good practice to have at least one Error Boundary at the very top level of your application, typically wrapping your main <App /> component or its immediate children (like routers or layout components).

// index.js or App.js
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
import RootErrorBoundary from './components/RootErrorBoundary'; // A specific EB for the root

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(
  <React.StrictMode>
    <RootErrorBoundary fallbackComponent={GlobalErrorFallbackUI}>
      <App />
    </RootErrorBoundary>
  </React.StrictMode>
);
  • Purpose: Acts as a final safety net. If an error occurs that isn't caught by a more specific, nested Error Boundary, this top-level one will catch it.
  • Fallback UI: The fallback for this boundary should be very generic, perhaps informing the user that a critical error occurred and suggesting they refresh or contact support. It acknowledges the app is in a broken state.
  • Logging: This boundary is critical for logging unexpected, widespread failures.

2.2 - Route-Level Error Boundaries​

When using a router (like React Router), wrapping individual route components or groups of routes with an Error Boundary is highly effective.

// App.js (with React Router)
import { Routes, Route } from 'react-router-dom';
import ErrorBoundary from './components/ErrorBoundary';

const HomePage = React.lazy(() => import('./pages/HomePage'));
const UserProfilePage = React.lazy(() => import('./pages/UserProfilePage'));
const SettingsPage = React.lazy(() => import('./pages/SettingsPage'));
// ... other page imports

function App() {
  return (
    <div>
      <Navbar />
      <Suspense fallback={<div>Loading page...</div>}>
        <Routes>
          <Route path="/" element={
            <ErrorBoundary fallbackComponent={PageErrorFallback} key="home">
              <HomePage />
            </ErrorBoundary>
          } />
          <Route path="/profile/:userId" element={
            <ErrorBoundary fallbackComponent={PageErrorFallback} key="profile">
              <UserProfilePage />
            </ErrorBoundary>
          } />
          <Route path="/settings" element={
            <ErrorBoundary fallbackComponent={SettingsPageErrorFallback} key="settings"> {/* Specific fallback */}
              <SettingsPage />
            </ErrorBoundary>
          } />
          {/* A general error boundary for a group of less critical routes */}
          <Route path="/info/*" element={
            <ErrorBoundary fallbackComponent={InfoSectionErrorFallback} key="info">
              <InfoRoutes /> {/* Assume InfoRoutes contains more nested routes */}
            </ErrorBoundary>
          } />
        </Routes>
      </Suspense>
      <Footer />
    </div>
  );
}
  • Purpose: If an error occurs on the UserProfilePage, only that page's content area is replaced by the fallback. The Navbar, Footer, and other routes remain accessible.
  • key Prop: Notice the key prop on the ErrorBoundary when used with routes. If you navigate between routes that use the same instance of an ErrorBoundary component (e.g., if you had one ErrorBoundary wrapping the entire <Routes> block), an error on one route might put the boundary into an error state, and it wouldn't automatically reset when navigating to another route. By providing a unique key per route (or per route component instance), you ensure that if the user navigates away from a broken route and then back, or to another route protected by a new instance of ErrorBoundary with a different key, the boundary will be in a fresh state. Alternatively, the reset mechanisms discussed in Part 2 of creating the ErrorBoundary can handle this.
  • Contextual Fallbacks: You can provide different fallback UIs for different routes or sections (e.g., SettingsPageErrorFallback).

2.3 - Widget/Component-Level Boundaries​

Wrap individual UI widgets, components, or "islands" of functionality that are distinct and could potentially fail without affecting the rest of the page.

Examples:

  • A social media feed widget on a dashboard.
  • A complex data visualization chart.
  • A third-party embedded map or chat widget.
  • A comments section.
  • An advertisement display component.
function DashboardPage() {
  return (
    <div>
      <MainKPIs />
      <ErrorBoundary fallbackComponent={ChartErrorFallback}>
        <SalesChartWidget />
      </ErrorBoundary>
      <ErrorBoundary fallbackComponent={FeedErrorFallback}>
        <ActivityFeedWidget />
      </ErrorBoundary>
      <TodoList />
    </div>
  );
}
  • Purpose: If SalesChartWidget crashes, MainKPIs, ActivityFeedWidget, and TodoList can still function.
  • User Experience: The user might see "Sales chart is temporarily unavailable" but can continue using other parts of the dashboard.

2.4 - Boundaries Around Third-Party Components​

Components from third-party libraries can sometimes be a source of unexpected errors, especially after library updates. Wrapping them in an Error Boundary can protect your application.

import ThirdPartyCalendar from 'some-calendar-library';
import ErrorBoundary from './components/ErrorBoundary';

function MyPageWithCalendar() {
  return (
    <div>
      <h2>My Schedule</h2>
      <ErrorBoundary fallbackComponent={CalendarUnavailableFallback}>
        <ThirdPartyCalendar events={...} />
      </ErrorBoundary>
    </div>
  );
}
  • Purpose: Prevents an error in ThirdPartyCalendar from crashing your entire MyPageWithCalendar or app.

🛠️ Section 3: Contextual Fallback UIs​

The more granular your Error Boundaries, the more opportunity you have to provide contextually relevant fallback UIs.

  • Generic App-Level Fallback: "Our apologies, a critical error occurred. Please refresh or contact support."
  • Page-Level Fallback: "Sorry, we couldn't load this page. Try going back or navigating to another section."
  • Widget-Level Fallback: "The [Widget Name] is currently unavailable. Please try again later." (And perhaps a button to try resetting that specific boundary).

Our reusable ErrorBoundary from the previous articles supports a fallback or fallbackComponent prop, making it easy to provide these different UIs:

// Using fallbackComponent for a specific widget
<ErrorBoundary fallbackComponent={SalesChartErrorUI}>
  <SalesChart />
</ErrorBoundary>

// SalesChartErrorUI.jsx
const SalesChartErrorUI = ({ error, resetError }) => (
  <div className="widget-error">
    <h4>Sales Chart Unavailable</h4>
    <p>We couldn't load the sales data at this moment.</p>
    <button onClick={resetError}>Try to reload chart</button>
    {process.env.NODE_ENV === 'development' && <pre>{error.message}</pre>}
  </div>
);

This makes the error experience much more informative and less disruptive for the user.

🔬 Section 4: General Best Practices and Considerations​

  1. Start Broad, Then Refine: If you're adding Error Boundaries to an existing application, start with a top-level boundary and then identify critical sections (routes, major widgets) to add more granular boundaries. Don't try to wrap everything initially.
  2. Consider the User Impact: When deciding on granularity, think about what the user can still do if a particular section fails. If a small, non-critical widget failing causes a large section of the UI to be replaced by a fallback, your boundary might be too coarse.
  3. Keep Fallbacks Simple: Fallback UIs themselves should be simple and unlikely to throw errors. Avoid complex logic or data fetching within a fallback UI.
  4. Logging is Key: Ensure your Error Boundaries (especially higher-level ones) are logging errors to a reporting service. This is how you'll find out about problems in production.
  5. Reset Functionality: For boundaries that wrap dynamic content or components that might recover from transient errors, provide a way for the user to "try again" (as built into our reusable ErrorBoundary).
  6. Development vs. Production Fallbacks:
    • In development, it's useful for fallbacks to display detailed error messages and stack traces.
    • In production, fallbacks should be user-friendly and avoid exposing technical details. Use process.env.NODE_ENV === 'development' to conditionally render such details.
  7. Lazy Loaded Components: Error Boundaries are essential when using React.lazy, as they can catch errors that occur if a code chunk fails to load (e.g., due to network issues). Wrap your Suspense components (or the lazy components themselves) with an Error Boundary. 
    <ErrorBoundary fallbackComponent={ChunkLoadErrorFallback}>
      <Suspense fallback={<Spinner />}>
        <MyLazyLoadedComponent />
      </Suspense>
    </ErrorBoundary>
  8. Don't Overuse for Control Flow: Error Boundaries are for unexpected errors. Don't use them to handle expected error conditions or as a substitute for proper conditional rendering or input validation (e.g., don't throw an error just because a form field is empty; handle that with normal application logic).

✨ Section 5: Example Scenario - E-commerce Product Page​

Let's consider an e-commerce product page and where Error Boundaries might be placed:

<App>
  <RootErrorBoundary> {/* 1. Top Level */}
    <Navbar />
    <Router>
      <Routes>
        <Route path="/product/:id" element={
          <ErrorBoundary fallbackComponent={ProductPageErrorUI} key="productPage"> {/* 2. Page Level */}
            <ProductDetailPage>
              <ProductImageGallery />
              <ProductInfoPanel />
              <ErrorBoundary fallbackComponent={ReviewsErrorUI} key="reviewsWidget"> {/* 3. Widget Level */}
                <ProductReviewsWidget />
              </ErrorBoundary>
              <ErrorBoundary fallbackComponent={RecommendationsErrorUI} key="recsWidget"> {/* 3. Widget Level */}
                <RecommendedProductsStore />
              </ErrorBoundary>
            </ProductDetailPage>
          </ErrorBoundary>
        } />
        {/* Other routes */}
      </Routes>
    </Router>
    <Footer />
  </RootErrorBoundary>
</App>

Reasoning:

  1. RootErrorBoundary: Catches any unhandled errors anywhere.
  2. ProductPageErrorUI Boundary: If the main product detail fetching or rendering fails, this shows a page-specific error, but Navbar and Footer remain. The key helps if navigating between different product pages.
  3. ReviewsErrorUI / RecommendationsErrorUI Boundaries:
    • The reviews section or recommendations carousel might fetch data from different microservices or be more prone to issues.
    • If reviews fail to load, the user can still see product details, images, and recommendations.
    • These provide very specific fallbacks (e.g., "Reviews currently unavailable," "Can't load recommendations right now").

This layered approach provides a good balance of safety and user experience.

💡 Conclusion & Key Takeaways​

Deciding where to place Error Boundaries is an art as much as a science, guided by your application's structure and the desired user experience in failure scenarios. By strategically wrapping routes, distinct UI sections, and potentially risky third-party components, you can build applications that are significantly more resilient and user-friendly when errors inevitably occur.

Key Takeaways:

  • The placement of Error Boundaries involves a trade-off in granularity.
  • Common strategies include top-level, route-level, and widget-level boundaries.
  • Always consider wrapping third-party components.
  • Tailor fallback UIs to be contextual to the part of the app protected by the boundary.
  • Use unique key props on Error Boundaries for routed components if not relying solely on the boundary's internal reset mechanism.
  • Prioritize logging and provide reset mechanisms where appropriate.

➡️ Next Steps​

Now that we understand how to build and strategically place Error Boundaries using class components, what about functional components? While Error Boundaries themselves must be classes, we often want to handle errors within or around our functional components. The next article, "Using Error Boundaries with Hooks (Part 1)", will explore how to use our class-based ErrorBoundary with functional components and discuss libraries that offer hook-like solutions for error handling.

Keep building robust and user-centric applications!

glossary​

  • Granularity (in Error Boundaries): Refers to how large or small a section of the UI is protected by a single Error Boundary.
  • Contextual Fallback: A fallback UI that is specific and relevant to the part of the application that experienced an error.
  • UI Widget/Island: A distinct, often self-contained section or component of a user interface (e.g., a chart, a feed, a user profile card).
  • Third-Party Component: A React component imported from an external library or package.

Further Reading​