React Error Boundaries: Where to Put Them and What to Show

A single uncaught error in React crashes the whole component tree. A well-placed error boundary limits the damage to a single section. After six months of refining this in production, here is where I put boundaries, what I show users, and what I log.

What An Error Boundary Does

An error boundary is a React component that catches errors in its child tree. When something throws below it, instead of the whole app going white, the boundary renders a fallback UI:

'use client';
export class Boundary extends React.Component<{children: ReactNode}, {error?: Error}> {
  state = {} as {error?: Error};
  static getDerivedStateFromError(error: Error) {
    return { error };
  }
  componentDidCatch(error: Error, info: React.ErrorInfo) {
    logError(error, info);
  }
  render() {
    if (this.state.error) return <Fallback />;
    return this.props.children;
  }
}

That is the whole mechanism. The question is where to wrap things.

Where I Put Boundaries

I put boundaries at three levels:

1. Route level: one boundary per page, catches anything the page throws
2. Widget level: around third-party embeds or experimental features
3. Never at the leaf level: boundaries that wrap single components are overkill

Route-level boundaries let one page break without killing the navigation. Widget-level boundaries let an ad, a chart, or an AI-generated section fail without taking the surrounding page. Leaf-level boundaries are usually noise.

What I Show Users

The fallback UI should be useful, not apologetic:

• A clear statement that something went wrong
• A way to recover (reload, retry, go back)
• A support path (contact, error ID to reference)

What I do not show:

• Raw error messages (they leak implementation details)
• Stack traces (confusing and unhelpful)
• Sorry animations (they mask the problem)

What I Log

Every error that hits a boundary gets logged with:

• Error name and message
• Component stack from ErrorInfo
• User ID if known
• Current route
• Browser and version

That log goes to the same system as my backend logs, tagged as frontend so I can filter. Seeing frontend and backend errors in one place is worth the setup cost.

The Server Components Angle

In Next.js, server components cannot use class-based boundaries. You use error.tsx files per route segment instead. Same concept, different mechanism. The route-level placement is what matters, not the class syntax.

The React error boundary documentation covers the full API.