React Error Boundaries Explained with a Reusable Example

React error boundaries are class components that catch rendering errors in their child components and show a fallback instead of a blank screen. They turn one broken widget into a recoverable part of the page. React still has no function-component equivalent, so the boundary stays a small class.

What an error boundary catches

An error boundary catches errors thrown while a child component renders. If a child throws, React walks up to the nearest boundary, swaps in its fallback, and keeps the rest of the app mounted.

It does not catch errors in event handlers, async code, server rendering, or the boundary itself. That distinction decides whether a crash is a render bug or a logic bug. See why error boundaries do not catch every error for the exact list.

Write the reusable class

A boundary needs a static getDerivedStateFromError to flip an error flag, and an optional componentDidCatch to log the failure.

App.jsx

import { Component } from "react";
 
export default class ErrorBoundary extends Component {
  state = { hasError: false };
  static getDerivedStateFromError() {
    return { hasError: true };
  }
 
  componentDidCatch(error, info) {
    console.error(error, info.componentStack);
  }
 
  render() {
    if (this.state.hasError) {
      return this.props.fallback;
    }
    return this.props.children;
  }
}

getDerivedStateFromError returns the next state so the following render shows the fallback. It must stay pure.

componentDidCatch runs after React records the error and is the right place for logging or an error-reporting call. The info.componentStack shows the path from the boundary to the component that threw.

Wrap a section with the fallback

Use the boundary around the part of the page that may crash, and pass a fallback that the user can understand. Keep the boundary close to the risky subtree so a failure only hides that widget, not the whole page.

App.jsx

import ErrorBoundary from "./ErrorBoundary.js";
 
function Fallback() {
  return (
    <p role="alert">
      The dashboard widget could not load.
    </p>
  );
}
 
export default function Dashboard({ data }) {
  return (
    <ErrorBoundary fallback={<Fallback />}>
      <RevenueChart data={data} />
    </ErrorBoundary>
  );
}

When RevenueChart throws during render, the boundary renders the Fallback component and the rest of the page keeps working. The alert role announces the failure to screen readers instead of leaving the change silent.

Reset after a failure

Once the error flag is true, the boundary keeps showing the fallback forever. The simplest recovery is to remount the boundary with a new key.

App.jsx

<ErrorBoundary key={version} fallback={<Fallback />}>
  <RevenueChart data={data} />
</ErrorBoundary>

Changing the key tells React this is a fresh boundary, so the error flag resets to false and the child renders again. A retry button that bumps the version gives users a way back after a transient failure.

When not to build your own

The react-error-boundary package provides the same class plus reset and logging props. Use it when you want the behavior without maintaining the class, and when you need a reset API, error metadata, or Hook-based recovery out of the box. For a minimal app, the short class above is the whole mechanism.

What to learn next

For pinning down the component that threw before you add a boundary, follow the systematic debugging loop. Loading is a separate concern handled by Suspense, not by error boundaries.