Skip to content

ErrorBoundary

X-08 · Composites · App components

All elements · ErrorBoundary on the Composites page

Last checked 2026-10-22 · Awaiting approval · Accessibility tests

Copies the bun run a11y:approve command for ErrorBoundary.

ErrorBoundary

X-08WCAG 2.2 AA · Passed #452

Three levels wrap an EmptyState[variant=error]. Dialogs get one automatically. Component-level keeps the rest of the page alive.

The specimen below is copied from error-boundary.html, which shows it inside the app shell, by bun scripts/design-pages/build-composite-pages.mjs — edit that file, not this one; --check fails when they drift.

Axis Values
.qf-error-boundary[data-level] app · page · component
__details · __stack collapsible technical detail
Component-level fallback

Guidance

When to use

  • Use it around any region that renders data and can throw, so one failure does not blank the page.
  • Use data-level="component" around a panel, such as a property tab, so the rest of the page keeps working.
  • Use data-level="page" when the page's own content failed but the shell still works.
  • Use data-level="app" only when the whole app failed to render; it fills the viewport.
  • Dialogs get one automatically; do not add another inside a dialog.

When to consider something else

  • Use a Banner for a recoverable error the user can fix, such as a failed save. See Banner.
  • Use a Toast for a short notice that an action failed in the background. See Toast.
  • Use an Empty state when the region worked but has no data. See EmptyState.
  • Use the Form error summary for validation errors. See Form.

Usability

Do
  • Say what failed and what still works: This panel failed to render. The rest of the page is unaffected.
  • Show the error ID so users can quote it to support.
  • Offer Try again and Copy details as actions.
  • Keep technical detail collapsed in .qf-error-boundary__details.
Don’t
  • Do not show the stack trace open by default.
  • Do not use the app level for a single failed panel.
  • Do not blame the user or use vague text such as Something went wrong alone.

Accessibility

Keyboard

ErrorBoundary keyboard
Keys Action
Tab Moves to Copy details, Try again and the Technical details summary.
Enter or Space On the Technical details summary, expands or collapses the stack.
Enter or Space On Try again, re-renders the failed region.

Roles and names

  • The boundary wraps an EmptyState with data-variant="error"; its icon is aria-hidden.
  • Details use native <details> and <summary>, which expose expanded state.
  • The binding should give the boundary role="alert" when it replaces content after the page loaded, or role="status" for a component level that is not urgent.
  • The title should be a heading at the level of the region it replaces, so screen reader users can find it.

Focus

  • At page and app level, move focus to the error title or Try again when the boundary appears.
  • At component level, do not move focus unless focus was inside the failed region; then move it to the boundary.
  • After Try again succeeds, move focus to the first control of the restored region.

Other requirements

  • The stack <pre> scrolls (overflow: auto); give it tabindex="0" and a name so keyboard users can scroll it (2.1.1).
  • The error state must be identified by text, not only the red dashed border or icon (1.4.1).
  • The stack text uses light ink on a dark tint; keep it at 4.5:1 in both themes (1.4.3).

Test your implementation too. This guidance covers the element as specified here. How a screen composes it (labels, order, announcements) still needs its own keyboard and screen reader check.

Accessibility tests

WCAG 2.2 AA · Passed

Passed the gate (run 358b316 on 2026-10-22): no finding in any theme. Awaiting a person’s approval of the checklist below.

ErrorBoundary test checklist
Area Automated A person checks
General Passed Color is never the only cue, text alternatives say the same thing as the graphic, and the element reads the same in the light and the dark theme.
Zoom Passed At 200% zoom, at 320 CSS pixels wide and with the WCAG text-spacing overrides, nothing is lost, clipped or overlapping.
Keyboard Passed Every row of the Keyboard table works, focus is always visible and never trapped, and the tab order follows the reading order. (3 rows)
Screen reader Passed With NVDA or JAWS on Windows and VoiceOver on macOS, names, roles and states are announced as Roles and names says, and changes are announced once. (4 items)

Approving. When the checklist passes on the checked run, record it with bun run a11y:approve -- error-boundary --by "Your name" and commit a11y/approvals.json with the rebuilt pages. All test status

Package

Consumers link one stylesheet, css/classic/index.css, which includes every element. The files below are where this element is defined.

ErrorBoundary package
Source css/classic/composites/feedback.css
Specimens also use Box · Button · Card · Chip · EmptyState · Icon · Table · Text · Toolbar
Sprites sprites/icons.svg
React Not yet available: the React binding has not started.

Latest updates

No recorded changes yet.

All release notes