Skip to content

Toast

C-20 · Components · Feedback

All elements · Toast on the Components page

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

Copies the bun run a11y:approve command for Toast.

Toast

C-20WCAG 2.2 AA · Passed #413

A Banner in a Toast shell, queued in a fixed region. Preserves the imperative toaster.* API. Five-second timer bar; dedupe by key.

Axis Values
.qf-toast-region[data-position] bottom-right (default) · top-center · bottom-left
.qf-toast[data-state=exiting] · __timer lifecycle
Fire toasts (bottom-right region)
Static toast
Task completed
Approve invoice INV-2026-0412
Timing (2.2.1)

A timed toast pauses while it is hovered or focused and resumes when the pointer and focus leave. A toast with an action has no timer: it stays until it is dismissed or its action is used.

Guidance

When to use

  • Confirm that an action just finished, such as Saved or Export started, without interrupting the user.
  • Offer a short Undo right after a reversible action, such as completing a task.
  • Report a background failure that does not block the current view, such as a document that could not be deleted.
  • Raise toasts from anywhere in the app through the imperative toaster.* API, deduplicated by key.

When to consider something else

  • When the condition lasts or needs action to fix, use Banner, which stays until it is resolved. See Banner.
  • When the user must decide before continuing, use Confirmation. See Confirmation.
  • When the user needs a record of the event later, also send it to Notifications. See NotificationCenter.
  • When the message is about one field, show it in the Field. See Field.

Usability

Do
  • Keep the title to a few words and the message to one line.
  • Use one action at most, such as Undo or View, plus dismiss.
  • Deduplicate repeated toasts with a key so the queue does not fill with copies.
  • Pick one data-position for the app; bottom-right is the default.
Don’t
  • Don't put the only way to do something in a toast; Undo must also be possible elsewhere, such as from history.
  • Don't use toasts for errors the user must fix before going on.
  • Don't show a toast for every row in a bulk action; summarize, such as "12 tasks approved".

Accessibility

Keyboard

Toast keyboard
Keys Action
Tab / Shift+Tab Reaches the toast's action and dismiss buttons where the region sits in the page order.
Enter or Space Activates the focused action or dismisses the toast.
Escape Required: the binding should dismiss the focused toast.

Roles and names

  • .qf-toast-region is a fixed region with aria-live="polite"; it must be in the page before any toast is added.
  • Each .qf-toast has role="status"; an error toast may use role="alert".
  • The toast wraps a Banner, so the title and message carry the severity in words; the icon is decorative.
  • The dismiss button has aria-label="Dismiss"; the __timer bar is decorative.

Focus

  • A toast never takes focus when it appears.
  • If the user tabs into a toast, it must not vanish while focused; when it is dismissed, return focus to where the user was.
  • The binding should offer a way to reach the latest toast from the keyboard, such as a shortcut, because the region is far from most focus positions.

Other requirements

  • The static toast auto-dismisses after 5 seconds; the binding must pause the timer while the toast is hovered or focused, and toasts with an action should not time out (2.2.1).
  • The slide-in and timer animations stop under prefers-reduced-motion (2.3.3).
  • Toasts must not cover the content users are working on, including the focused element (2.4.11), and must fit within 320px width (1.4.10).
  • Success, warning and error tones need 4.5:1 text and a 3:1 accent edge (1.4.3, 1.4.11).

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.

Toast 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)

Conditional

Toast conditional criteria
Criterion Context Demonstrated
2.2.1 Timing Adjustable The auto-dismiss timer pauses while the toast is hovered or focused, and a toast with an action never times out. The timer belongs to the binding, so a live demo must show it before the chip can be earned. Yes

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

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