Lorixen.
EN

React error boundaries: stop one crash blanking the page

Short answer: In a React app, an error thrown while rendering one small component can make the whole page go blank. React's documentation says that by default, if your application throws an error during rendering, React removes its UI from the screen. Error boundaries are components that catch those errors and show a fallback for just the broken part, such as "This section couldn't load", while the rest of the page keeps working. Wrap independent sections, not every component, report what the boundary catches to your error tracker, and remember boundaries do not catch errors in event handlers or async code.

Why one bad widget can blank the page

Business apps built with React often show many independent pieces on one screen: an order list, a stats panel, a chat widget, a recommendations carousel. If one of them receives unexpected data, say a missing field from an API, and throws during render, React cannot be sure what the correct UI is. Its documented default is to remove the UI, which to a customer or staff member looks like a white screen and a broken app.

That is a poor trade. Nine sections were fine, and one failure took them all down.

What an error boundary does

The React docs describe an error boundary as a special component that lets you display fallback UI instead of the part that crashed, for example an error message. You wrap part of your component tree in it. When something inside throws during rendering, the boundary shows its fallback, and everything outside it carries on.

Technically, an error boundary is a class component that implements static getDerivedStateFromError, to switch to the fallback, and optionally componentDidCatch, to log the error. React's documentation notes that there is currently no way to write an error boundary as a function component, but you do not have to write the class yourself; it points to the react-error-boundary package as an option. Most teams write one boundary component, or install that package, and reuse it everywhere.

Where to put boundaries

React's guidance is about granularity. Its example is a messaging app: it makes sense to place a boundary around the list of conversations and around each individual message, but not around every avatar.

For a typical business app:

  • One at the top, around the whole app, showing a friendly "Something went wrong, reload the page" screen instead of a blank one.
  • One per major section, such as each dashboard panel, the product reviews block or the order history table.
  • One around third-party or experimental components, such as embedded maps, chat widgets or new features behind a flag.
  • One per route or page, so an error on the reports page does not stop someone using navigation to go elsewhere.

Avoid wrapping tiny pieces like icons or labels; a boundary should surround something a user would recognise as a unit.

Design the fallback, not just the catch

A fallback is part of your user experience. Good fallbacks:

  • Say what failed in plain words: "We couldn't load your recent orders."
  • Offer a way forward: a retry button that resets the boundary, a link to the full page or a support contact.
  • Keep the layout stable, roughly the same size as the content it replaces, so the page does not jump.
  • Never show raw error messages or stack traces to customers.

The react-error-boundary package offers a reset mechanism so a "Try again" button can re-render the section, which suits temporary data problems well.

Report what you catch

A boundary that hides errors without telling anyone makes problems harder to find. Use componentDidCatch, or the package's onError option, to send the error and its component stack to your error-tracking tool.

React 19's createRoot also accepts root-level callbacks. Its documentation lists onCaughtError, called when React catches an error in an error boundary, and onUncaughtError, called when an error is thrown and not caught by one. Each receives the error and an object containing the component stack, so you can route both to monitoring in one place.

What boundaries don't catch

React's earlier documentation spells out the limits. Error boundaries do not catch errors in:

  • Event handlers, such as an onClick that throws.
  • Asynchronous code, such as setTimeout or requestAnimationFrame callbacks.
  • Server-side rendering.
  • The error boundary itself, as opposed to its children.

For event handlers and async work, use ordinary try and catch, show an inline error or toast, and report the error yourself. Data-fetching libraries often have their own error states that work alongside boundaries.

Test that they work

Boundaries are easy to add and easy to get subtly wrong, so check them deliberately. In a development or staging build, make one component throw on purpose, for instance with a temporary query parameter that triggers an error in the reviews block, and confirm three things: the fallback appears in the right place, the rest of the page still responds, and the error arrives in your tracker with a readable component stack. Repeat for the top-level boundary. Many teams keep a small automated test for each fallback so a refactor cannot quietly remove it.

A worked example

Picture a hypothetical Seattle field-services company whose technicians use a React web app on tablets. The job screen showed customer details, a parts list, a map and a notes panel. When the map provider occasionally returned an unexpected response, the map component threw and the whole job screen went blank in the field.

The developers added a top-level boundary with a reload screen, plus boundaries around the map, parts list and notes panel. The map fallback now reads "Map unavailable, open address in your maps app" with a link. Caught errors go to the error tracker with the component stack, which showed the exact response shape that broke the map, and a fix followed within a day.

FAQ

Do error boundaries work with Next.js or other frameworks?

Yes. Frameworks built on React use the same mechanism, and some add conventions such as an error file per route.

Will a boundary stop the error from being logged in development?

No. In development React still shows the error so you can fix it.

Should I catch every error with a boundary?

Only rendering errors. Handle expected failures, like a failed fetch, as normal states in your components.

If parts of your React app sometimes take down the whole screen, describe which screens fail and how.

Sources

WhatsAppBook a call