React Reference ยท Components and Special Elements
Error boundary classes
Reference for React error boundaries: write a class with getDerivedStateFromError and componentDidCatch, reset it, and know which errors it cannot catch.
An error boundary is a component that catches errors thrown while its descendants render, shows a fallback instead, and keeps the rest of the app running. Without one, an error during rendering unmounts the whole React tree and leaves a blank page.
There is no hook for this. A boundary must be a class component that defines static getDerivedStateFromError, componentDidCatch, or both. Most projects write one boundary class and reuse it, or install a small library that wraps the same two methods.
class Boundary extends Component { state = { error: null }; static getDerivedStateFromError(error) { return { error }; } render() { return this.state.error ? <p>Oops</p> : this.props.children; } }
Try it
An error thrown directly inside save would not reach the boundary, because event handlers run outside rendering. Rethrowing it from a state updater moves the failure into the render phase, so the boundary shows its fallback. Many apps instead show an inline error message for handler failures and keep boundaries for render problems.
Syntax
class Boundary extends Component { static getDerivedStateFromError(error: unknown): Partial<State> | null; componentDidCatch(error: unknown, info: { componentStack: string }): void; }
| Method | Description |
|---|---|
getDerivedStateFromError(error) |
Runs during rendering after a descendant threw. Return an object to merge into state, normally { error }. Must be pure: no side effects. |
componentDidCatch(error, info) |
Runs after the fallback was committed. Use it for logging and reporting. info.componentStack lists the components that were rendering. |
What counts as an error: anything thrown while rendering, in constructors, in lifecycle methods of descendants, and rejections surfaced by use or by lazy loading.
What is not caught: errors in event handlers, in setTimeout or promise callbacks, in server rendering, and errors thrown by the boundary itself. A boundary cannot catch its own failure; the next boundary above does.
Usage notes
- Reset with state or a key. Clear the error from state (as in the first example), or change the boundary's
keyto remount it and its children. Reset when the thing that caused the error changes, such as the route or the data. - Place several. One boundary at the root prevents a blank page; extra boundaries around widgets, routes or lists limit the damage. See the error boundaries lesson.
- Logging. In development React also prints caught errors to the console; this is expected. In production, report in
componentDidCatchor with the root optionsonCaughtErrorandonUncaughtError(createRoot options). - State is lost. The children below the boundary are unmounted when the fallback shows, so their local state is gone.
- Re-render loops. If the fallback itself can throw, or the boundary resets without fixing the cause, you get a loop. Keep fallbacks simple.
- Libraries. Packages such as
react-error-boundaryoffer a ready-made component withresetKeysand hooks (read-only here, not installed in the editor). They still use the same two class methods internally. - Only the render path. A boundary does not stop an effect from failing silently or a network call from rejecting; handle those where they happen.