react-error-boundary/README.md

Simple reusable React error boundary component

<img src="https://react-error-boundary-lib.vercel.app/og.png" alt="react-error-boundary logo" width="400" height="210" />

`react-error-boundary`: Reusable React [error boundary](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary) component. Supports all React renderers (including React DOM and React Native).

### If you like this project, 🎉 [become a sponsor](https://github.com/sponsors/bvaughn/) or ☕ [buy me a coffee](http://givebrian.coffee/)

> [!NOTE]
> Projects using framework or runtimes that don't support ES Modules should use version 5 of this library.

## Getting started

```sh
# npm
npm install react-error-boundary

# pnpm
pnpm add react-error-boundary

# yarn
yarn add react-error-boundary
```

## Documentation

Read the [react-error-boundary docs](https://react-error-boundary-lib.vercel.app/) for examples, API reference, and troubleshooting. The docs also include a [frequently asked questions guide](https://react-error-boundary-lib.vercel.app/common-questions).

## Quick start

Wrap an `ErrorBoundary` around the part of the tree where you want to show a fallback UI if rendering fails. Your fallback can call `resetErrorBoundary` to clear the error and retry rendering:

```tsx
"use client";

import { ErrorBoundary, getErrorMessage } from "react-error-boundary";

export default function App() {
  return (
    <ErrorBoundary
      fallbackRender={({ error, resetErrorBoundary }) => (
        <div role="alert">
          <p>Something went wrong:</p>
          <pre>{getErrorMessage(error)}</pre>
          <button onClick={resetErrorBoundary}>Try again</button>
        </div>
      )}
      onError={(error, info) => {
        // Log the error to your error reporting service
      }}
      onReset={() => {
        // Reset any state that may have caused the error
      }}
    >
      {/* Components protected by this boundary */}
    </ErrorBoundary>
  );
}
```

## What errors are caught?

This package is built on top of React [error boundaries](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary), so it follows React's rules for what errors are caught.

Error boundaries catch errors thrown while rendering the tree below them.

Error boundaries do not catch errors thrown during:

- Server side rendering
- Event handlers
- Errors thrown in the error boundary itself
- Async code that runs after rendering, like `setTimeout` callbacks or unresolved promises

## Async errors

For async errors:

- Use `useErrorBoundary` to pass caught errors to the nearest boundary.
- In React 19, `useTransition` Actions can be an alternative: errors thrown from a function passed to the returned `startTransition` function are caught by the nearest boundary.

```tsx
"use client";

import { useTransition } from "react";
import { ErrorBoundary } from "react-error-boundary";

function UserProfileContainer({ username }: { username: string }) {
  return (
    <ErrorBoundary fallback={<p>Could not load profile</p>}>
      <UserProfile username={username} />
    </ErrorBoundary>
  );
}

function UserProfile({ username }: { username: string }) {
  const [isPending, startTransition] = useTransition();

  function loadProfile() {
    startTransition(async () => {
      await fetchUserProfile(username);
    });
  }

  return (
    <button disabled={isPending} onClick={loadProfile}>
      {isPending ? "Loading..." : "Load profile"}
    </button>
  );
}
```

## API

### ErrorBoundary

<!-- ErrorBoundary:description:begin -->
A reusable React [error boundary](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary) component.
Wrap this component around other React components to "catch" errors and render a fallback UI.

Catches errors thrown while rendering the tree below it.

Does not catch errors thrown during:
- Server side rendering
- Event handlers
- Errors thrown in the error boundary itself
- Async code that runs after rendering, like `setTimeout` callbacks or unresolved promises

Async errors:

- Use `useErrorBoundary` to pass caught errors to the nearest boundary
- In React 19, errors thrown from a function passed to the `startTransition` function returned by `useTransition`
  are caught by the nearest boundary

ℹ️ The component provides several ways to render a fallback: `fallback`, `fallbackRender`, and `FallbackComponent`.
Refer to the documentation to determine which is best for your application.

ℹ️ This is a **client component**. You can only pass props to it that are serializable or use it in files that have a `"use client";` directive.
<!-- ErrorBoundary:description:end -->

#### Required props

<!-- ErrorBoundary:required-props:begin -->
None
<!-- ErrorBoundary:required-props:end -->

#### Optional props

<!-- ErrorBoundary:optional-props:begin -->

<table>
  <thead>
    <tr>
      <th>Name</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>onError</td>
      <td><p>Optional callback to enable e.g. logging error information to a server.
@param error Value that was thrown; typically an instance of <code>Error</code>
@param info React &quot;component stack&quot; identifying where the error was thrown</p>
</td>
    </tr>
    <tr>
      <td>onReset</td>
      <td><p>Optional callback to be notified when an error boundary is reset so React can retry the failed render.</p>
</td>
    </tr>
    <tr>
      <td>resetKeys</td>
      <td><p>When changed, these keys will reset a triggered error boundary.
This can be useful when an error condition may be tied to some specific state (that can be uniquely identified by key).
See the documentation for examples of how to use this prop.</p>
</td>
    </tr>
    <tr>
      <td>fallback</td>
      <td><p>Static content to render in place of an error if one is thrown.</p>
<pre><code class="language-tsx">&lt;ErrorBoundary fallback={&lt;div className=&quot;text-red&quot;&gt;Something went wrong&lt;/div&gt;} /&gt;
</code></pre>
</td>
    </tr>
    <tr>
      <td>FallbackComponent</td>
      <td><p>React component responsible for returning a fallback UI based on a thrown value.</p>
<pre><code class="language-tsx">&lt;ErrorBoundary FallbackComponent={Fallback} /&gt;
</code></pre>
</td>
    </tr>
    <tr>
      <td>fallbackRender</td>
      <td><p><a href="https://react.dev/reference/react/Children#calling-a-render-prop-to-customize-rendering">Render prop</a> function responsible for returning a fallback UI based on a thrown value.</p>
<pre><code class="language-tsx">&lt;ErrorBoundary fallbackRender={({ error, resetErrorBoundary }) =&gt; &lt;div&gt;...&lt;/div&gt;} /&gt;
</code></pre>
</td>
    </tr>
  </tbody>
</table>

<!-- ErrorBoundary:optional-props:end -->

# FAQ
## `ErrorBoundary` cannot be used as a JSX component
This error can be caused by a version mismatch between [react](https://npmjs.com/package/react) and [@types/react](https://npmjs.com/package/@types/react). To fix this, ensure that both match exactly, e.g.:

If using NPM:
```json
{
  ...
  "overrides": {
    "@types/react": "17.0.60"
  },
  ...
}
```

If using Yarn:
```json
{
  ...
  "resolutions": {
    "@types/react": "17.0.60"
  },
  ...
}
```

---

[This blog post](https://kentcdodds.com/blog/use-react-error-boundary-to-handle-errors-in-react) shows more examples of how this package can be used, although it was written for the [version 3 API](https://github.com/bvaughn/react-error-boundary/releases/tag/v3.1.4).