Error boundaries

An Error Boundary catches errors thrown during render and shows a fallback instead of unmounting the tree. It is a component that wraps a subtree: if any descendant throws while rendering, the boundary swaps that subtree for its fallback UI. As of React 19 there is still no Hook form — an error boundary is a class component implementing getDerivedStateFromError (to render the fallback) and optionally componentDidCatch (to log). The react-error-boundary package is the standard wrapper most teams use instead of hand-rolling it.

import { Component, type ReactNode } from "react";

class ErrorBoundary extends Component<
  { fallback: ReactNode; children: ReactNode },
  { hasError: boolean }
> {
  state = { hasError: false };
  static getDerivedStateFromError() {
    return { hasError: true };   // render the fallback on the next render
  }
  componentDidCatch(error: Error) {
    reportToSentry(error);       // side-effect: log it
  }
  render() {
    return this.state.hasError ? this.props.fallback : this.props.children;
  }
}

Without a boundary, a render-time throw propagates up the tree and React unmounts everything from the nearest boundary upward — and if there’s no boundary at all, the entire root. That unmount is the blank white screen.

Suspense handles loading; an Error Boundary handles failed — a real async UI needs both, stacked. A pending data fetch suspends (Suspense catches it and shows the fallback). A rejected data fetch throws (the Error Boundary catches it and shows its fallback). They are two different signals for two different states, caught by two different boundaries. The Error Boundary goes above the Suspense, because a failure should replace the whole loading region — including its skeleton — not render inside it.

// The pairing. Outer = failed state, inner = loading state.
<ErrorBoundary fallback={<FeedError />}>
  <Suspense fallback={<FeedSkeleton />}>
    <ActivityFeed />   {/* pending → skeleton; rejected → FeedError */}
  </Suspense>
</ErrorBoundary>

Read it top-down: while ActivityFeed’s data is pending, the user sees FeedSkeleton; if it resolves, they see the feed; if it rejects, the throw escapes Suspense, hits the Error Boundary, and they see FeedError. Three states, fully handled.

Give the boundary a reset so the user can retry the failed region without reloading the page. A catch-and-show-fallback that has no way back is a dead end. react-error-boundary exposes a resetErrorBoundary() callback to your fallback; calling it clears the error state and re-renders the children, which re-runs the suspended fetch. Pair it with a resetKeys array so the boundary also auto-resets when an input (like the user id) changes.

import { ErrorBoundary } from "react-error-boundary";

function FeedSection({ userId }: { userId: string }) {
  return (
    <ErrorBoundary
      FallbackComponent={FeedError}
      resetKeys={[userId]}         // auto-reset when userId changes
    >
      <Suspense fallback={<FeedSkeleton />}>
        <ActivityFeed userId={userId} />
      </Suspense>
    </ErrorBoundary>
  );
}

function FeedError({ resetErrorBoundary }: { resetErrorBoundary: () => void }) {
  return (
    <div role="alert">
      <p>Couldn't load the feed.</p>
      <button onClick={resetErrorBoundary}>Retry</button>
    </div>
  );
}

Now a transient failure is recoverable in place: the user clicks Retry, the region drops back into its FeedSkeleton, and the fetch runs again — no full-page reload, no losing the rest of the screen.

The sharp edge: Error Boundaries only catch render-phase errors. Errors in event handlers, effects, timeouts, and async callbacks are NOT caught. This is the failure mode that surprises people. getDerivedStateFromError runs during rendering, so it only sees throws that happen during render (including a Suspense child whose read rejected). A throw inside an onClick, a setTimeout, a fetch().then(...), or the body of a useEffect happens outside render — React doesn’t route it to the boundary, and it either crashes the handler silently or surfaces as an unhandled rejection.

function SaveButton() {
  // ❌ NOT caught by any Error Boundary — this is a handler, not render.
  async function onSave() {
    await api.save();          // if this rejects, the boundary never sees it
  }
  return <button onClick={onSave}>Save</button>;
}

// ✅ Handle event/effect errors yourself — try/catch + local error state.
function SaveButton() {
  const [err, setErr] = useState<string | null>(null);
  async function onSave() {
    try { await api.save(); }
    catch { setErr("Save failed. Try again."); }
  }
  return (
    <>
      <button onClick={onSave}>Save</button>
      {err && <p role="alert">{err}</p>}
    </>
  );
}

So Error Boundaries are necessary but not sufficient: they cover the render path (data fetching for components that read on render, bad props, a component that throws while rendering), and you still owe a separate strategy — try/catch plus local state, or your data layer’s error handling — for everything that happens in handlers and effects.