Error Boundary

Usage

Overview

ErrorBoundary catches render-time errors in child trees and shows a fallback while the rest of the app keeps running. In dispatch, it prevents a single misbehaving chart, map overlay, or third-party widget from white-screening the entire console—aligned with resilient dashboard patterns in large enterprise UIs.

When to use

Heavy or risky widgets (analytics charts, maps, media players, experimental panels).
Lazy-loaded feature islands where dependency failures are plausible.
Third-party integrations that may throw during data shape changes.

When not to use

As a substitute for handling async errors in event handlers—use try/catch and user-visible error states.
Sprinkled at every component without strategy—too many boundaries complicate debugging and duplicate fallbacks.
To silently swallow errors—always report to observability.

Variants

Fallback UI should be calm: short explanation, retry when safe, link to support or docs for internal tools. Match product voice; use formatMessage for strings.

Anatomy

Boundary wrapper, children, fallback renderer, onError sink to logging/monitoring.

Content guidelines

User-facing messages explain impact (“This chart failed to load”) not stack traces.
Retry actions should be explicit about what will rerun.

Behavior and states

Reset keys when upstream data changes so recovered trees remount cleanly.
Do not loop retry on deterministic failures—back off and show contact paths.

Best practices

Do scope boundaries to feature panels so one failure does not blank chat, radio, or incident core.
Do implement onError with the observability pipeline every time—never silent catches.
Don’t nest dozens of boundaries without ownership—prefer a few well-owned frontiers.
Don’t use boundaries to hide known validation issues—fix data contracts.

Accessibility

Fallback content must be focusable and readable; announce errors politely if using live regions.
Ensure retry controls are keyboard accessible.

Dynamic importer for lazy boundaries paired with import errors.
Banner for recoverable data errors surfaced inline.
Empty state when absence is expected, not exceptional.

Empty text / Accessibility

Error Boundary / API and Development

On this page

Error Boundary

Usage

Overview

When to use

Heavy or risky widgets (analytics charts, maps, media players, experimental panels).
Lazy-loaded feature islands where dependency failures are plausible.
Third-party integrations that may throw during data shape changes.

When not to use

As a substitute for handling async errors in event handlers—use try/catch and user-visible error states.
Sprinkled at every component without strategy—too many boundaries complicate debugging and duplicate fallbacks.
To silently swallow errors—always report to observability.

Variants

Fallback UI should be calm: short explanation, retry when safe, link to support or docs for internal tools. Match product voice; use formatMessage for strings.

Anatomy

Boundary wrapper, children, fallback renderer, onError sink to logging/monitoring.

Content guidelines

User-facing messages explain impact (“This chart failed to load”) not stack traces.
Retry actions should be explicit about what will rerun.

Behavior and states

Reset keys when upstream data changes so recovered trees remount cleanly.
Do not loop retry on deterministic failures—back off and show contact paths.

Best practices

Do scope boundaries to feature panels so one failure does not blank chat, radio, or incident core.
Do implement onError with the observability pipeline every time—never silent catches.
Don’t nest dozens of boundaries without ownership—prefer a few well-owned frontiers.
Don’t use boundaries to hide known validation issues—fix data contracts.

Accessibility

Fallback content must be focusable and readable; announce errors politely if using live regions.
Ensure retry controls are keyboard accessible.

Dynamic importer for lazy boundaries paired with import errors.
Banner for recoverable data errors surfaced inline.
Empty state when absence is expected, not exceptional.

Empty text / Accessibility

Error Boundary / API and Development

On this page