react-error-boundary

react-error-boundary is a small, dependency-free React library that wraps React’s error boundary API in an ergonomic, reusable component. Drop an ErrorBoundary around any part of your component tree to catch errors thrown while rendering and display a fallback UI instead of a blank screen or a crashed app.

Beyond the core component, it ships a useErrorBoundary hook for forwarding event-handler and async errors to the nearest boundary, a withErrorBoundary higher-order component, reset keys and imperative reset for recovery, and full TypeScript types. It supports every React renderer, including React DOM and React Native, and works with React 18 and 19.

What You Get

• An ErrorBoundary component supporting three fallback strategies: static fallback, fallbackRender render prop, and FallbackComponent.
• A useErrorBoundary hook to forward event-handler and async errors to the nearest boundary and to imperatively reset it.
• A withErrorBoundary higher-order component for wrapping components without extra JSX nesting.
• resetKeys plus an imperative resetErrorBoundary API and onError / onReset callbacks for logging and recovery.
• First-class TypeScript types and support for React 18 and 19 across all renderers, including React Native.

Common Use Cases

• Preventing a single component’s render error from crashing the entire application.
• Showing a friendly retry UI when a widget, route, or dashboard panel fails to render.
• Logging render errors to an external monitoring service via the onError callback.
• Recovering from an error automatically when relevant state changes using resetKeys.
• Forwarding errors from event handlers or async callbacks to a boundary with useErrorBoundary.

Under The Hood

Architecture — The core is a single class component, ErrorBoundary in lib/components/ErrorBoundary.tsx, that uses React’s getDerivedStateFromError to flip a discriminated-union state to { didCatch: true, error } and componentDidCatch to invoke the onError callback. Its render method selects among fallback, fallbackRender, and FallbackComponent, throwing the original error if none is provided, and always wraps children in an ErrorBoundaryContext.Provider so descendants can read didCatch, error, and resetErrorBoundary. componentDidUpdate compares resetKeys with a hasArrayChanged helper (guarded against resetting on the first update after catching) to auto-recover. The useErrorBoundary hook (lib/hooks/useErrorBoundary.ts) reads that context to forward async/handler errors, and withErrorBoundary (lib/utils/withErrorBoundary.ts) provides an HOC wrapper.

Tech Stack — Written in TypeScript targeting React 18 or 19 as the sole peer dependency, with zero runtime dependencies. The library entry point lib/index.ts is marked "use client" and re-exports the component, context, hook, HOC, and getErrorMessage utility alongside their types. Bundling is handled by Vite (vite.config.ts) emitting ESM and CJS builds plus .d.ts types via vite-plugin-dts; the repo also contains a full Vite + react-router documentation site under src/.

Code Quality — Types are the standout: lib/types.ts models the mutually exclusive fallback props as a discriminated union (ErrorBoundaryPropsWithFallback | ...WithComponent | ...WithRender) using never guards so invalid combinations fail at compile time. Test coverage is present and colocated — ErrorBoundary.test.tsx, useErrorBoundary.test.tsx, and withErrorBoundary.test.tsx — run under Vitest with Testing Library and jsdom, with vitest-fail-on-console enforcing clean output. Naming is explicit and the code is small, readable, and consistently formatted with Prettier and ESLint.

API Design — The public surface is deliberately minimal and ergonomic: one component with three well-documented fallback strategies, a hook, and an HOC cover the common cases with little boilerplate. JSDoc on every prop, a dedicated documentation site, and clear guidance on what errors boundaries do and do not catch make the developer experience excellent, and the discriminated-union typing means editors surface the right props for the chosen fallback strategy.