{"id":11700,"library":"react-error-boundary","title":"React Error Boundary","description":"`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.","status":"active","version":"6.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/bvaughn/react-error-boundary","tags":["javascript","react","reactjs","virtual","window","windowed","list","scrolling","infinite","typescript"],"install":[{"cmd":"npm install react-error-boundary","lang":"bash","label":"npm"},{"cmd":"yarn add react-error-boundary","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-error-boundary","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency, required for React component functionality.","package":"react","optional":false}],"imports":[{"note":"Since v6.0.0, the package is ESM-only. CommonJS `require` will not work.","wrong":"const ErrorBoundary = require('react-error-boundary')","symbol":"ErrorBoundary","correct":"import { ErrorBoundary } from 'react-error-boundary'"},{"note":"This Higher-Order Component (HOC) wraps a component with an error boundary. Ensure named import is used.","wrong":"import withErrorBoundary from 'react-error-boundary/withErrorBoundary'","symbol":"withErrorBoundary","correct":"import { withErrorBoundary } from 'react-error-boundary'"},{"note":"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`).","symbol":"getErrorMessage","correct":"import { getErrorMessage } from 'react-error-boundary'"}],"quickstart":{"code":"import React, { useState } from 'react';\nimport { ErrorBoundary } from 'react-error-boundary';\n\ninterface BombProps { \n  shouldThrow: boolean;\n}\n\nfunction Bomb({ shouldThrow }: BombProps) {\n  if (shouldThrow) {\n    throw new Error('💥 Kaboom 💥');\n  }\n  return <p>All good!</p>;\n}\n\nfunction ErrorFallback({ error, resetErrorBoundary }: { error: Error; resetErrorBoundary: () => void }) {\n  return (\n    <div role=\"alert\">\n      <p>Something went wrong:</p>\n      <pre style={{ color: 'red' }}>{error.message}</pre>\n      <button onClick={resetErrorBoundary}>Try again</button>\n    </div>\n  );\n}\n\nexport function App() {\n  const [hasError, setHasError] = useState(false);\n  const [errorCount, setErrorCount] = useState(0);\n\n  const reset = () => {\n    setHasError(false);\n    setErrorCount(prev => prev + 1);\n  };\n\n  return (\n    <div>\n      <p>Error count: {errorCount}</p>\n      <button onClick={() => setHasError(true)}>Cause Error</button>\n      <ErrorBoundary\n        FallbackComponent={ErrorFallback}\n        onReset={reset}\n        resetKeys={[errorCount]} // Reset the boundary when errorCount changes\n      >\n        <Bomb shouldThrow={hasError} />\n      </ErrorBoundary>\n    </div>\n  );\n}","lang":"typescript","description":"Demonstrates basic usage of ErrorBoundary with a FallbackComponent and `onReset` to recover from errors. It shows how to trigger and reset an error state."},"warnings":[{"fix":"Migrate your import statements from CommonJS `require()` to ES module `import` syntax. Ensure your project is configured for ESM.","message":"Version 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.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Review and update the type definitions for components wrapped with `withErrorBoundary` and `forwardRef` to match the new React type requirements.","message":"Version 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.","severity":"breaking","affected_versions":">=5.0.0"},{"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.","message":"React 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Using `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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`).","cause":"This error commonly occurs due to a version mismatch between `react` and `@types/react`, or incorrect TypeScript configuration.","error":"ErrorBoundary cannot be used as a JSX component"},{"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.","cause":"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.","error":"ReferenceError: require is not defined"},{"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.","cause":"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.","error":"Invalid hook call. Hooks can only be called inside of the body of a function component."}],"ecosystem":"npm"}