React Error Boundaries

The other week I got an email from a developer wondering if I could help them learn more about Error Boundaries within React.

I figured that instead of sharing that information directly to them, I would spend a bit more time writing it up in a blog post so others could learn from the content as well. This post is only meant as a brief introduction to the concept behind Error Boundaries within React, for more advanced information refer to the where can I learn more section at the bottom of the page.

So lets dive in!

What are Error Boundaries?

Simply put, you can think of Error Boundaries as try ... catch blocks within a component tree. This is an example of a try catch block:

1try {
2  doSomethingThatMayThrow();
3} catch (error) {
4  handleError(error);
5}

1try {
2  doSomethingThatMayThrow();
3} catch (error) {
4  handleError(error);
5}

In that snippet above, the doSomethingThatMayThrow function can throw anything (generally an error) and the catch block will capture this thrown value and continue script execution.

In React this would look like something like the following:

1<ErrorBoundary>
2  <ComponentThatMayThrow />
3</ErrorBoundary>;

1<ErrorBoundary>
2  <ComponentThatMayThrow />
3</ErrorBoundary>;

Great, so we have a rough understanding of what they look like in practice, but how do they actually work?

How do Error Boundaries Work?

An error boundary can be implemented within any component that uses either the:

• componentDidCatch or
• getDerivedStateFromError

lifecycle methods. Both of these methods allow the component to catch an error thrown from its children.

So lets setup a simple generic Error Boundary component.

1class ErrorBoundary extends React.Component {
2  state = {
3    hasCaughtError: false,
4  };
5  componentDidCatch(error) {
6    this.setState({ hasCaughtError: true });
7  }
8  render() {
9    if (this.state.hasCaughtError) {
10      return <p>Oh no, an error has occurred</p>;
11    }
12    return this.props.children;
13  }
14}

1class ErrorBoundary extends React.Component {
2  state = {
3    hasCaughtError: false,
4  };
5  componentDidCatch(error) {
6    this.setState({ hasCaughtError: true });
7  }
8  render() {
9    if (this.state.hasCaughtError) {
10      return <p>Oh no, an error has occurred</p>;
11    }
12    return this.props.children;
13  }
14}

In this component above, whenever some component anywhere within its children throws an error, React will propagate that error up to this component, and call its componentDidCatch lifecycle method with the error that was thrown.

This component can then setState to change the children returned from render in order to recover from that thrown error.

Caveats

As with most things, there are some caveats with this workflow. The first and most notable, is that this component will only catch errors thrown during the render phase. This means that if an error occurs within a callback that is not a setState updater, the error boundary component will not catch it.

Another caveat, or feature I guess is that if you do want to catch a particular error from an event handler higher up in the component tree at your error boundary, you can throw from within a setState:

1import { Component } from 'react';
2
3// Note this is a live editor!
4// Feel free to toy around with the code and see the
5// actual output above!
6export default class Example extends Component {
7  handleChange = (e) => {
8    let {
9      target: { value },
10    } = e;
11    this.setState(() => {
12      if (value.includes('foo')) {
13        throw new Error('Error!');
14      }
15      return null;
16    });
17  };
18  render() {
19    return (
20      <input
21        onChange={this.handleChange}
22        placeholder='Try typing here!'
23        style={{
24          height: 35,
25          fontSize: 18,
26          width: 'calc(100% - 2em)',
27          padding: '1rem',
28        }}
29      />
30    );
31  }
32}

1import { Component } from 'react';
2
3// Note this is a live editor!
4// Feel free to toy around with the code and see the
5// actual output above!
6export default class Example extends Component {
7  handleChange = (e) => {
8    let {
9      target: { value },
10    } = e;
11    this.setState(() => {
12      if (value.includes('foo')) {
13        throw new Error('Error!');
14      }
15      return null;
16    });
17  };
18  render() {
19    return (
20      <input
21        onChange={this.handleChange}
22        placeholder='Try typing here!'
23        style={{
24          height: 35,
25          fontSize: 18,
26          width: 'calc(100% - 2em)',
27          padding: '1rem',
28        }}
29      />
30    );
31  }
32}

A note on getDerivedStateFromError

The getDerivedStateFromError lifecycle was introduced later than the componentDidCatch lifecycle, and operates on a similar mechanism as the getDerivedStateFromProps lifecycle method in that it is a single pass handler. This means that React is able to reconcile the error handling within the same rendering batch as when the error occurs, I think. I don't really understand what this actually means however, so take this with a grain of salt 🧂 .

Where can I learn more?

As always, the ReactJS first party docs site is hands down one of the best resources out there about React. Here is a great getting started introduction to Error Boundaries on the ReactJS Docs.