Error boundaries

Bugs happen. Data arrives in a shape you did not expect, a value you assumed exists turns out to be missing, a library has an edge case. When that happens while React is rendering, the result is harsh: by default React removes the entire app from the screen. One broken book card means a blank page.

An error boundary is a component that catches errors thrown by components inside it and shows a fallback UI instead, while the rest of the app keeps working. Think of it as a try/catch for a part of your component tree.

When rendering failsCopy Anchor Link

Click "Show covers" below. One book has bad data, and the cover component throws.

The preview shows an error instead of your app. The heading, the button and the unrelated paragraph are all gone. React does this on purpose: rather than leave a half-broken, possibly misleading UI on screen, it unmounts everything. Click the refresh icon on the preview to start over.

The fix for the bug is to handle missing colors. But you cannot foresee every bug, so you also want a safety net that limits the damage.

Catching errors with react-error-boundaryCopy Anchor Link

React's own docs are blunt: there is currently no way to write an error boundary as a function component. It has to be a class component, which this course otherwise never uses. You do not need to write that class yourself, though. The small, widely used react-error-boundary package provides a ready-made ErrorBoundary, and react.dev recommends it. Install it with npm install react-error-boundary.

Now only the part inside the boundary is replaced. The heading, the button and the paragraph survive. Notice that the whole boundary's content is replaced, including The Hobbit's cover, which was fine. A boundary swaps out everything inside it, so where you put it decides how much disappears.

Showing details and letting users recoverCopy Anchor Link

A fixed message is a start. Usually you want to show what went wrong and offer a way out. Instead of fallback, pass a FallbackComponent. It receives two props:

• error: whatever was thrown. Its type is unknown, because JavaScript lets you throw anything, so you check error instanceof Error before reading .message.
• resetErrorBoundary: a function that clears the error and renders the children again.

The boundary can also reset automatically when something changes. Pass resetKeys={[selectedId]}, and when selectedId changes while an error is showing, the boundary resets and tries again.

In the sandbox, the third book has no rating and crashes the details panel. Pick it, then pick another book.

Four props did the work:

• FallbackComponent renders the friendly panel with the real message.
• resetKeys={[selectedId]} resets the boundary when you pick a different book, so the user is never stuck on the error.
• onReset runs on every reset. Its details.reason is 'keys' for a resetKeys change and 'imperative-api' when resetErrorBoundary was called, so the button can move back to a book that works.
• onError is called once per caught error. In a real app you send the error to a service like Sentry here.

What boundaries do not catchCopy Anchor Link

Error boundaries catch errors thrown while React renders components inside them. They do not catch errors thrown:

• inside event handlers, like onClick;
• in asynchronous code, like a setTimeout callback or after an await;
• in the error boundary component itself.

That is because those errors do not happen during rendering. React is not on the call stack, so it cannot catch them. For event handlers, a normal try/catch is often enough. When you want such an error to show the nearest boundary's fallback, react-error-boundary gives you the useErrorBoundary hook. Its showBoundary(error) function hands the error to the nearest boundary.

This one fails about half the time, so click "Load reviews" a few times. Here "Try again" makes sense, because the failure is random, like a flaky network. fallbackRender is a third way to give a fallback: a function that receives the same props as FallbackComponent.

Under the hood: the class versionCopy Anchor Link

For the curious, this is roughly what an error boundary looks like if you write it yourself. It is the only class component in this course, and you do not need to memorize it.

import { Component } from 'react';
import type { ErrorInfo, ReactNode } from 'react';

interface Props {
  fallback: ReactNode;
  children: ReactNode;
}

interface State {
  hasError: boolean;
}

export class ErrorBoundary extends Component<Props, State> {
  state: State = { hasError: false };

  // Runs during rendering when a child throws: switch to the fallback.
  static getDerivedStateFromError(): State {
    return { hasError: true };
  }

  // Runs after the error is caught: a good place to log it.
  componentDidCatch(error: unknown, info: ErrorInfo) {
    console.error(error, info.componentStack);
  }

  render() {
    return this.state.hasError ? this.props.fallback : this.props.children;
  }
}

The two special methods, static getDerivedStateFromError and componentDidCatch, have no hook equivalents yet. That is the whole reason error boundaries are still classes. react-error-boundary is this same idea plus resetting, fallback components and the showBoundary hook.

import type { ReactNode } from 'react';
import { ErrorBoundary } from 'react-error-boundary';
import { CurrentlyReading, Goal, Streak } from './widgets';

function Widget({ children }: { children: ReactNode }) {
  return (
    <ErrorBoundary fallback={<section className="card failed">This widget failed to load.</section>}>
      {children}
    </ErrorBoundary>
  );
}

export default function App() {
  return (
    <div className="grid">
      <Widget>
        <CurrentlyReading />
      </Widget>
      <Widget>
        <Streak />
      </Widget>
      <Widget>
        <Goal />
      </Widget>
    </div>
  );
}