React Error Boundaries: Containing UI Crashes

Why it exists

Before Error Boundaries, any JavaScript error inside a component during rendering would corrupt React's internal state and cause the entire app to unmount, showing a blank page. This provided a terrible user experience for recoverable errors. Error Boundaries were created to solve this by localizing the damage.

The mental model

An Error Boundary is a special React component that acts like an electrical circuit breaker for your component tree. When a component inside it "trips" by throwing an error during rendering, the boundary catches the error, cuts off the broken part of the tree, and renders a fallback UI in its place. The rest of the application keeps running normally.

How it works

You create an Error Boundary by defining a class component with one or both of these lifecycle methods: static getDerivedStateFromError(error) and componentDidCatch(error, errorInfo). When a child component throws an error, React calls getDerivedStateFromError first. This method should return a state object to update the boundary's state, triggering a re-render to show a fallback UI. Then, componentDidCatch is called, which is useful for side effects like logging the error. Crucially, there is no function component equivalent; you must use a class component for Error Boundaries.

When to use it

Use Error Boundaries to wrap distinct parts of your application that can fail independently. Good candidates are complex data visualizations, third-party widgets you don't control, or any feature that might encounter unexpected API responses during render. Place them at a strategic level—not around every button, but around logical sections of your app.

When not to use it

Error Boundaries do NOT catch all errors. They miss errors inside event handlers (like onClick), asynchronous code (like setTimeout or fetch calls), server-side rendering, and errors thrown in the error boundary component itself. For these, you must use standard JavaScript try...catch blocks and promise .catch() handlers.

One canonical example

To use it, you wrap a component like this: <ErrorBoundary><MyRiskyComponent /></ErrorBoundary>. The boundary itself is a class that uses state to decide whether to render its children or a fallback UI. It uses getDerivedStateFromError to update that state and componentDidCatch to log the error details, like this: class ErrorBoundary extends React.Component { constructor(props) { super(props); this.state = { hasError: false }; } static getDerivedStateFromError(error) { return { hasError: true }; } componentDidCatch(error, info) { logErrorToService(error, info.componentStack); } render() { if (this.state.hasError) { return <h1>Something went wrong.</h1>; } return this.props.children; } }