ErrorBoundary

When to useLink to "When to use"

• Around each part that can fail on its own: a tab's body, a side panel, a chart, a plugin's view.
• Once around the whole app, as the last line, with a fallback that offers a reload.

Use something else when:

• an operation failed (a request, a save): show it where it happened with a Notice or a Toast. Boundaries only catch errors thrown while rendering, not in event handlers or asynchronous code.
• there is nothing to show yet: EmptyState.

UsageLink to "Usage"

import { ErrorBoundary } from "@arshad-shah/cynosure";

<ErrorBoundary label="Query results" resetKey={tabId} onError={(error, info) => report(error, info.componentStack)}>
  <ResultsPanel />
</ErrorBoundary>

Healthy children render as they are, with no wrapper element, so a boundary never changes the layout of a flex or grid parent.

Retry and resetLink to "Retry and reset"

The default fallback's "Try again" button renders the children again; if they still throw, the fallback comes back. A change of resetKey (compared with Object.is) does the same without the button: pass what the content depends on, such as the active tab or route.

Your own fallbackLink to "Your own fallback"

fallback gets the error and retry. Anything thrown that is not an Error (a string, say) arrives wrapped in one.

<ErrorBoundary
  fallback={(error, retry) => (
    <EmptyState title="The chart could not be drawn" description={error.message} actions={<Button onClick={retry}>Reload</Button>} />
  )}
>
  <Chart />
</ErrorBoundary>

NestingLink to "Nesting"

The nearest boundary catches the error: an inner one around the editor keeps the window's sidebar and status bar on screen, and the outer one's onError is not called.

PropsLink to "Props"

Behaviour and accessibilityLink to "Behaviour and accessibility"

• Announcement: the default fallback is a danger Notice (role="alert"), so the failure is announced when it appears. Its heading names the part with label ("Query results could not be shown"; "Something went wrong" without one), and the error's message follows.
• Reporting: onError(error, info) is called once per caught error, with React's component stack in info.componentStack.
• Labels: labels replaces the English text: a title(label) function and the retry button's text.

TouchLink to "Touch"

The retry button is a small Button, with a 44px hit area on coarse pointers.

ThemingLink to "Theming"

The message itself is a Notice: restyle it with --cy-notice-* tokens.

RelatedLink to "Related"

Notice, EmptyState, Toast