Registry / web-framework / react-error-boundary

react-error-boundary

library6.1.1jsnpmunverified

`react-error-boundary` is a lightweight, reusable React component designed to catch JavaScript errors in a component tree, log them, and display a fallback UI without crashing the entire application. It is built on top of React's native error boundary API and supports all React renderers, including React DOM and React Native. The current stable version is 6.1.1, with a regular release cadence addressing bug fixes and minor improvements. Key differentiators include its straightforward API that directly leverages React's built-in error boundary capabilities, offering `fallback`, `FallbackComponent`, and `fallbackRender` props for flexible error UI presentation. It also provides `onReset` and `resetKeys` for handling error recovery, and ships with comprehensive TypeScript types for an improved developer experience.

web-framework

npm install react-error-boundary

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-ERROR-BOUNDA

react-error-boundary

web-frameworkjavascriptv6.1.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ErrorBoundary

✓ import { ErrorBoundary } from 'react-error-boundary'

✗ const ErrorBoundary = require('react-error-boundary')

Since v6.0.0, the package is ESM-only. CommonJS `require` will not work.

withErrorBoundary

✓ import { withErrorBoundary } from 'react-error-boundary'

✗ import withErrorBoundary from 'react-error-boundary/withErrorBoundary'

This Higher-Order Component (HOC) wraps a component with an error boundary. Ensure named import is used.

getErrorMessage

✓ import { getErrorMessage } from 'react-error-boundary'

A helper method exported since v6.1.0 to safely extract an error message from a thrown value, which might not always be an Error instance (e.g., `unknown`).

Demonstrates basic usage of ErrorBoundary with a FallbackComponent and `onReset` to recover from errors. It shows how to trigger and reset an error state.

import React, { useState } from 'react'; import { ErrorBoundary } from 'react-error-boundary'; interface BombProps { shouldThrow: boolean; } function Bomb({ shouldThrow }: BombProps) { if (shouldThrow) { throw new Error('💥 Kaboom 💥'); } return <p>All good!</p>; } function ErrorFallback({ error, resetErrorBoundary }: { error: Error; resetErrorBoundary: () => void }) { return ( <div role="alert"> <p>Something went wrong:</p> <pre style={{ color: 'red' }}>{error.message}</pre> <button onClick={resetErrorBoundary}>Try again</button> </div> ); } export function App() { const [hasError, setHasError] = useState(false); const [errorCount, setErrorCount] = useState(0); const reset = () => { setHasError(false); setErrorCount(prev => prev + 1); }; return ( <div> <p>Error count: {errorCount}</p> <button onClick={() => setHasError(true)}>Cause Error</button> <ErrorBoundary FallbackComponent={ErrorFallback} onReset={reset} resetKeys={[errorCount]} // Reset the boundary when errorCount changes > <Bomb shouldThrow={hasError} /> </ErrorBoundary> </div> ); }

Debug

Known issues

breakingVersion 6.0.0 made the module ESM-only to align with modern JavaScript tooling. This means `require()` syntax for importing `react-error-boundary` will no longer work.

fix

Migrate your import statements from CommonJS `require()` to ES module `import` syntax. Ensure your project is configured for ESM.

affects: >=6.0.0

breakingVersion 5.0.0 updated the TypeScript types for `withErrorBoundary` to be compatible with the latest `forwardRef` types in React. This may cause type errors in projects heavily relying on `withErrorBoundary` with `forwardRef` if not updated.

fix

Review and update the type definitions for components wrapped with `withErrorBoundary` and `forwardRef` to match the new React type requirements.

affects: >=5.0.0

gotchaReact Error Boundaries (and thus `react-error-boundary`) cannot catch errors in certain scenarios: event handlers, asynchronous code (e.g., `setTimeout`, promises, `async/await`), server-side rendering, or errors thrown within the error boundary component itself.

fix

For errors in event handlers or asynchronous code, use traditional `try/catch` blocks. Implement server-side error handling separately for SSR. Ensure your fallback UI logic is robust to avoid errors within the boundary itself.

affects: >=1.0.0

gotchaThe component provides three different props for rendering a fallback UI: `fallback`, `FallbackComponent`, and `fallbackRender`. Choosing the wrong one can lead to unexpected behavior or unnecessary re-renders.

fix

`fallback` is for static content. `FallbackComponent` expects a React component (props: `error`, `resetErrorBoundary`). `fallbackRender` expects a render prop function (args: `{ error, resetErrorBoundary }`). Choose based on whether you need dynamic logic or access to the error/reset function.

affects: >=1.0.0

gotchaUsing `resetKeys` is crucial for resetting an error boundary when the context changes, allowing React to retry rendering. If `resetKeys` are not properly managed, the boundary might remain in an error state even after the underlying cause is resolved.

fix

Pass an array of values to `resetKeys` that, when changed, should trigger a reset of the error boundary. This is often tied to state or props that, if updated, mean the component is ready to try rendering again.

affects: >=1.0.0

Errors

Common errors & fixes

ErrorBoundary cannot be used as a JSX component

This error commonly occurs due to a version mismatch between `react` and `@types/react`, or incorrect TypeScript configuration.

fix

Ensure `react` and `@types/react` versions are exactly matched in your `package.json`. If using npm, use `overrides`. If using yarn, use `resolutions`. Also, verify your `tsconfig.json` `jsx` setting is correct (e.g., `react-jsx`).

ReferenceError: require is not defined

Attempting to import `react-error-boundary` using CommonJS `require()` syntax in a project that is configured for ES modules, or in a version that is ESM-only.

fix

Update your import statements from `const ErrorBoundary = require('react-error-boundary');` to `import { ErrorBoundary } from 'react-error-boundary';`. Ensure your project's `package.json` specifies `"type": "module"` if you intend to use ESM globally, or configure your build tools accordingly. This is a breaking change since v6.0.0.

Invalid hook call. Hooks can only be called inside of the body of a function component.

While `react-error-boundary` provides a functional component interface, it internally relies on React's class-based error boundaries. If you inadvertently try to use hooks directly within the `FallbackComponent` or `fallbackRender` props in a way that violates React's rules (e.g., conditional hooks), this can occur.

fix

Ensure that any custom `FallbackComponent` or the function passed to `fallbackRender` adheres strictly to React's rules of hooks, calling them unconditionally at the top level of a functional component. If logic requires conditional execution, move it inside an effect or memo hook, or use a custom hook.

Upgrade

Version history

6.1.1latest on npm

Audit

Dependencies

reactrequiredPeer dependency, required for React component functionality.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/bvaughn/react-error-boundary ↗

packagehttps://www.npmjs.com/package/react-error-boundary ↗

homepagehttps://react-error-boundary-lib.vercel.app/ ↗