# react-native-error-boundary: catching render errors in React Native apps

> react-native-error-boundary is a small TypeScript component that catches rendering errors in a React Native tree, renders a fallback UI and hands the error and stack trace to an onError callback. It only covers render-time failures, not async errors.

**carloscuesta/react-native-error-boundary** — A simple React-Native error boundary component 🐛

- Repository: https://github.com/carloscuesta/react-native-error-boundary
- Website: https://react-native-error-boundary.js.org
- Stars: 624 · Forks: 33
- Language: TypeScript
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/carloscuesta-react-native-error-boundary

## One component for render-time crashes, not every crash

A React Native app can crash in two very different ways. The first is a throw during render, a bad prop, a null dereference inside a component body, and React itself will unmount the tree and show a blank screen. The second is a throw in a promise, a network callback or an event handler, which React does not intercept at all.

react-native-error-boundary addresses the first category. It is described as a simple and reusable React Native error boundary component, and the documentation points at the React component lifecycle method for catching rendering errors. The scope is the whole subtree you wrap, so the practical decision is placement: wrap the app root and one unhandled render error anywhere inside replaces a white screen with a fallback view, or wrap individual screens and let the rest of the app keep running.

The API is small enough to read in a minute. The component takes Children as a required prop, an optional FallbackComponent that defaults to the library's own built-in component, and an optional onError function. There is no configuration object, no plugin, no native module, and no setup step beyond installing the package.

## What onError and resetError actually hand you

The recovery story runs through the fallback component, not through the boundary itself. When an error is caught, the fallback is rendered, and that fallback receives two props: the error object, and a resetError function described as a function to reset the error state, which you call to recover from the error state.

So the retry button in your fallback UI is a direct call to resetError. That design is the practical difference between this component and a plain crash screen: the error state is not terminal. The API reference lists the two fallback props as error of type Error and resetError of type Function, with the signatures shown as resetError(): void.

Reporting is handled through onError, which receives two arguments, the error caught by the component and the stack trace of the error:

```js
onError(error: Error, stackTrace: string): void
```

Because onError is a plain callback rather than a pluggable reporter, wiring it to Sentry, Bugsnag or your own endpoint is your job, and the library does not prescribe one. Note that the stack trace arrives as a string parameter, so the shape of what you forward to a reporting service is entirely up to you.

## Installing the package and rendering a first fallback

Installation is a single command, and the README gives the yarn form. The npm equivalent is the same package name.

```bash
yarn add react-native-error-boundary
```

The package publishes source and compiled output together. The package.json points main at lib/index.js and types at lib/index.d.ts, while a react-native field points consumers at src/index.tsx, so a React Native bundler reads the TypeScript source directly while plain Node resolution and type resolution use the built lib/ directory. The files array ships src, lib and README.md, and the build script is tsc.

A first use is just wrapping your tree and passing the two things the component understands. The FallbackComponent receives the error and the resetError callback, so a minimal fallback is a component that renders the message and offers a retry.

One dependency detail catches people. The peer dependencies list react at >=16.6.0, react-native at >=0.74.0 and react-native-safe-area-context at >=5.0.0. The safe area context peer is there because a fallback view occupies the whole screen, and without correct safe area insets the retry button can end up under a notch or a home indicator. If your app does not already depend on react-native-safe-area-context, you need to add it before the fallback is usable.

## The fallback is a component prop, so the built-in one is only a default

The default FallbackComponent exists so the component works on the first render, not so it is what you ship. The documentation lists the fallback props in a table with no defaults for error and resetError, which makes sense: a generic fallback can show something happened, but it cannot know what to offer the user next.

Two patterns follow from that. In the minimal case you keep the default and rely on onError to report, which gives you a crash report and a dead end for the user. In the fuller case you supply your own FallbackComponent that renders a message, a retry that calls resetError, and optionally a button that sends the user to a support screen. The boundary does not constrain what the fallback contains, so it can be a full screen with navigation.

Worth noting for sizing: a fallback that reloads the same screen after resetError will hit the same failure again if the underlying data is still bad. The reset clears the error state in the boundary, not the cause of the error. If your crash comes from a bad network response, the retry needs to refetch or the fallback needs to offer a different path.

## Where the boundary stops working, and why

This is the limitation that decides whether the package helps you. React error boundaries only catch errors thrown during rendering, in lifecycle methods and in constructors of the subtree below them. They do not catch errors in event handlers, in setTimeout callbacks, in promise rejections or in async code after an await. A fetch that rejects inside a useEffect is invisible to the boundary, and the app will log an unhandled rejection or crash on its own.

So the component is a rendering safety net, not an error strategy. If your crash budget is dominated by failed API calls or by a misbehaving third-party library, wrapping the app in ErrorBoundary changes almost nothing, and you need your own try/catch and error state for that path.

There is a second, quieter limitation. The boundary is a React component, so it cannot render while the React renderer itself is broken. If the failure is in native code, in a TurboModule bridge, or in the JavaScript engine startup path, the fallback UI never appears either, because it needs the same renderer to draw it.

## Comparing with a hand-rolled class boundary

Before React hooks, a boundary was a class component implementing componentDidCatch and getDerivedStateFromError. That is the mechanism this package is named after, and the keywords field in package.json lists componentDidCatch explicitly. A team that already has such a class can use it directly, and the difference is what this package adds.

The additions are the fallback prop contract, the resetError escape hatch, and a small set of props that keep the wrapping code readable. Writing your own class means maintaining your own error state, your own retry affordance and your own prop plumbing, and reimplementing them in every screen that needs isolation.

The counter-argument is dependency weight and opacity. The package brings a peer requirement on react-native-safe-area-context, and its behaviour is fixed by the library rather than by code you own, so a team that wants custom error state, custom telemetry and per-screen retry semantics may find it easier to keep a local boundary class and skip the dependency entirely. The trade is real: less code to write and less control over what happens.

## Maintenance, release cadence and what a new major means

The repository is not archived. The last push was on 2026-10-01, and the recent releases are 3.1.0 on 2025-10-31, 3.0.0 on 2025-10-08 and 2.0.0 on 2025-03-02. The gap between the last push and the last release shows that work continues on the branch without a tag, which is common for a library of this size but means master is not a stable reference.

The release tooling is visible in package.json. The version scripts are pnpm version patch, minor and major, each with an emoji commit message, and the repository carries a pnpm-lock.yaml even though the README instructs a yarn install, so the two package managers are both part of the project's history. There is also a husky setup through the prepare script, jest for tests, eslint and prettier for linting, a tsconfig for typechecking, and a babel.config.js. Continuous integration is wired through GitHub Actions, and a Codecov badge in the README points at coverage reporting.

The licence is MIT, so the code can be vendored, modified and redistributed with the notice retained. The thing to watch on upgrades is the peer dependency floor rather than the code: the minimum react-native of 0.74.0 and the react-native-safe-area-context floor of 5.0.0 are the parts that can force a change in your app, not the component itself.

## Conclusion

Adopt react-native-error-boundary when your React Native screens can crash during render and you want a fallback component plus an onError hook into your crash reporting, and skip it when your failures come from async code, network callbacks or event handlers, since it does not cover those. Before shipping it, confirm your React Native version is at least 0.74.0 and your React version at least 16.6.0, since those are the declared peer dependencies, and decide whether the built-in fallback is enough or you need your own FallbackComponent.

## FAQ

### How do I install react-native-error-boundary?

The README gives a single command: yarn add react-native-error-boundary. The package publishes compiled output at lib/index.js and points React Native bundlers at src/index.tsx through the react-native field.

### How do I log errors from react-native-error-boundary?

Pass an onError prop, which is called with two arguments, the error and its stack trace. The library does not ship a reporting service, so you forward those values to whatever crash reporter you already use.

### How can I offer a retry button after an error in react-native-error-boundary?

Supply your own FallbackComponent. It receives the error object and a resetError function, and calling resetError clears the error state so the boundary renders its children again.

### Does react-native-error-boundary catch errors in API calls and event handlers?

No. It catches errors thrown during rendering in the wrapped subtree, so promise rejections, network callbacks and event handlers are outside its reach and need their own handling.

### What are the peer dependencies of react-native-error-boundary?

The package declares react at >=16.6.0, react-native at >=0.74.0 and react-native-safe-area-context at >=5.0.0, so the safe area context package has to be present for the fallback screen to lay out correctly.

## Sources

- [carloscuesta/react-native-error-boundary on GitHub](https://github.com/carloscuesta/react-native-error-boundary)
- [License: MIT](https://github.com/carloscuesta/react-native-error-boundary/blob/master/LICENSE)
- [Project website](https://react-native-error-boundary.js.org)
- [README](https://github.com/carloscuesta/react-native-error-boundary/blob/master/README.md)
- [Releases](https://github.com/carloscuesta/react-native-error-boundary/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/carloscuesta-react-native-error-boundary