Skip to content

Banner

C-19 · Components · Feedback

All elements · Banner on the Components page

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

Copies the bun run a11y:approve command for Banner.

Guidance

When to use

  • Tell users about a condition that lasts while they work in a view, such as indexing in progress, offline or read-only.
  • Show an error or warning that needs action, with buttons in __actions, such as Save now or Retry.
  • Show a system-wide alert at the top of the app with data-variant="solid".
  • Show a message tied to a form section or field with data-variant="inline".
  • Choose the tone with data-severity: info, success, warning, error or neutral.

When to consider something else

  • When the message confirms an action that just happened and can go away on its own, use Toast. See Toast.
  • When the user must decide before continuing, such as deleting a record, use Confirmation. See Confirmation.
  • When the message is about one field's value, use Field's error or helper text. See Field.
  • When there is no content to show because of the condition, use Empty state. See EmptyState.
  • When the message belongs in the user's history of events, send it to Notifications. See NotificationCenter.

Usability

Do
  • Put the banner at the top of the area it is about, above the content.
  • Lead with a short __title and say what to do next in __message.
  • Keep actions to one or two buttons, the main one last.
  • Let users dismiss info and success banners with __close; keep errors until the cause is fixed.
Don’t
  • Don't stack more than two banners in one area; combine them or show the most severe.
  • Don't use a banner for a success message that needs no action; use Toast.
  • Don't use solid error banners for anything but system-wide problems.

Accessibility

Keyboard

Banner keyboard
Keys Action
Tab / Shift+Tab Moves to the banner's action buttons and the dismiss button; the banner itself is not focusable.
Enter or Space Activates the focused action or dismisses the banner.

Roles and names

  • Info and success banners use role="status" (polite); warning and error banners that appear after load use role="alert" (assertive).
  • Neutral banners and banners present when the page loads need no live role; a live role only announces content added after the region exists.
  • The live region must exist before its text is inserted, or screen readers may miss it.
  • The severity icon is decorative; the title or message must say the severity in words, such as "Upload failed".
  • The dismiss button has aria-label="Dismiss".

Focus

  • Showing a banner does not move focus.
  • When the user dismisses a banner, move focus to the next logical element, such as the start of the content below, so it is not lost.
  • Action buttons show the shared focus ring.

Other requirements

  • Severity is shown by icon, color and words, not color alone (1.4.1); text needs 4.5:1 on each soft and solid background (1.4.3).
  • Status messages must be announced without taking focus (4.1.3).
  • Banners must not disappear on a timer; users need time to read and act (2.2.1).
  • The dismiss button is extra small; keep it at least 24px or spaced from other targets (2.5.8).

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.

Banner 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. (2 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. (5 items)

Approving. When the checklist passes on the checked run, record it with bun run a11y:approve -- banner --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.

Banner package
Source css/classic/components/content.css
Specimens also use Box · Button · Card · Chip · 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