react-error-boundary
Reusable React error boundary component. Supports all React renderers (including React DOM and React Native).
If you like this project, 🎉 become a sponsor or ☕ buy me a coffee
Getting started
# npm
npm install react-error-boundary
# pnpm
pnpm add react-error-boundary
# yarn
yarn add react-error-boundaryAPI
ErrorBoundary component
Wrap an ErrorBoundary component around other React components to "catch" errors and render a fallback UI. The component supports several ways to render a fallback (as shown below).
Note
ErrorBoundaryis a client component. You can only pass props to it that are serializeable or use it in files that have a"use client";directive.
ErrorBoundary with fallback prop
The simplest way to render a default "something went wrong" type of error message.
"use client";
import { ErrorBoundary } from "react-error-boundary";
<ErrorBoundary fallback={<div>Something went wrong</div>}>
<ExampleApplication />
</ErrorBoundary>ErrorBoundary with fallbackRender prop
"Render prop" function responsible for returning a fallback UI based on a thrown value.
"use client";
import { ErrorBoundary } from "react-error-boundary";
function fallbackRender({ error, resetErrorBoundary }) {
// Call resetErrorBoundary() to reset the error boundary and retry the render.
return (
<div role="alert">
<p>Something went wrong:</p>
<pre style={{ color: "red" }}>{error.message}</pre>
</div>
);
}
<ErrorBoundary
fallbackRender={fallbackRender}
onReset={(details) => {
// Reset the state of your app so the error doesn't happen again
}}
>
<ExampleApplication />
</ErrorBoundary>;ErrorBoundary with FallbackComponent prop
React component responsible for returning a fallback UI based on a thrown value.
"use client";
import { ErrorBoundary } from "react-error-boundary";
function Fallback({ error, resetErrorBoundary }) {
// Call resetErrorBoundary() to reset the error boundary and retry the render.
return (
<div role="alert">
<p>Something went wrong:</p>
<pre style={{ color: "red" }}>{error.message}</pre>
</div>
);
}
<ErrorBoundary
FallbackComponent={Fallback}
onReset={(details) => {
// Reset the state of your app so the error doesn't happen again
}}
>
<ExampleApplication />
</ErrorBoundary>;Logging errors with onError
"use client";
import { ErrorBoundary } from "react-error-boundary";
const logError = (error: Error, info: { componentStack: string }) => {
// Do something with the error, e.g. log to an external API
};
const ui = (
<ErrorBoundary FallbackComponent={ErrorFallback} onError={logError}>
<ExampleApplication />
</ErrorBoundary>
);useErrorBoundary hook
Convenience hook for imperatively showing or dismissing error boundaries.
Show the nearest error boundary from an event handler
React only handles errors thrown during render or during component lifecycle methods (e.g. effects and did-mount/did-update). Errors thrown in event handlers, or after async code has run, will not be caught.
This hook can be used to pass those errors to the nearest error boundary:
"use client";
import { useErrorBoundary } from "react-error-boundary";
function Example() {
const { showBoundary } = useErrorBoundary();
useEffect(() => {
fetchGreeting(name).then(
response => {
// Set data in state and re-render
},
error => {
// Show error boundary
showBoundary(error);
}
);
});
// Render ...
}Dismiss the nearest error boundary
A fallback component can use this hook to request the nearest error boundary retry the render that originally failed.
"use client";
import { useErrorBoundary } from "react-error-boundary";
function ErrorFallback({ error }) {
const { resetBoundary } = useErrorBoundary();
return (
<div role="alert">
<p>Something went wrong:</p>
<pre style={{ color: "red" }}>{error.message}</pre>
<button onClick={resetBoundary}>Try again</button>
</div>
);
}withErrorBoundary HOC
This package can also be used as a higher-order component that accepts all of the same props as above:
"use client";
import {withErrorBoundary} from 'react-error-boundary'
const ComponentWithErrorBoundary = withErrorBoundary(ExampleComponent, {
fallback: <div>Something went wrong</div>,
onError(error, info) {
// Do something with the error
// E.g. log to an error logging client here
},
})
// Can be rendered as <ComponentWithErrorBoundary {...props} />FAQ
ErrorBoundary cannot be used as a JSX component
This error can be caused by a version mismatch between react and @types/react. To fix this, ensure that both match exactly, e.g.:
If using NPM:
{
...
"overrides": {
"@types/react": "17.0.60"
},
...
}If using Yarn:
{
...
"resolutions": {
"@types/react": "17.0.60"
},
...
}This blog post shows more examples of how this package can be used, although it was written for the version 3 API.