Skip to content

Confirmation

C-29 · Components · Overlays

All elements · Confirmation on the Components page

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

Copies the bun run a11y:approve command for Confirmation.

Confirmation

C-29WCAG 2.2 AA · Passed #422

Confirm-before-act in three presentations: dialog (Overlay sm), popover, and button (a button that opens either). Never a raw dialog.

Axis Values
data-presentation dialog · popover
confirmText · confirmColor · loading label, color and loading state of the confirm button
Dialog and popover
Archive this document? You can restore it from the archive later.
Delete document
Are you sure you want to delete INV-2026-0412.pdf? This cannot be undone.

Guidance

When to use

  • Use a confirmation before an action that cannot be undone, such as deleting a document.
  • Use the dialog presentation for destructive or high-impact actions; it blocks the page until the user decides.
  • Use the popover presentation for lower-risk actions that the user can reverse, such as archiving.
  • Use the button presentation to attach either form to the button that starts the action.

When to consider something else

  • If the action can be undone, skip the confirmation and show a toast with Undo. See Toast.
  • If the user needs to enter more than a reason or a name, use an overlay with a form. See Overlay.
  • If you are warning about a state on the page rather than an action, use a banner. See Banner.

Usability

Do
  • Ask a direct question that names the object: "Delete INV-2026-0412.pdf?".
  • Say what happens and whether it can be undone.
  • Label the confirm button with the action ("Delete", "Archive"), not "OK" or "Yes".
  • Use confirmColor error for destructive actions and show loading while the action runs.
Don’t
  • Don't use a raw browser confirm() dialog.
  • Don't ask for confirmation on routine, reversible actions; users learn to click through.
  • Don't put the destructive action where Cancel usually is.

Accessibility

Keyboard

Confirmation keyboard
Keys Action
Tab or Shift+Tab Moves between Cancel and the confirm button; the dialog form keeps focus inside.
Enter or Space Runs the focused button.
Escape Cancels and closes, in both presentations.

Roles and names

  • Both presentations use role="alertdialog".
  • The dialog form names itself with aria-labelledby on the title; the binding should also set aria-describedby on the message.
  • The popover form has no title, so it needs aria-label (or aria-labelledby on the trigger) and aria-describedby on .qf-confirm-popover__text.
  • The warning icon is decorative (aria-hidden="true").

Focus

  • On open, the binding must move focus into the confirmation; for destructive actions, focus Cancel first.
  • The dialog form traps focus as a modal; the popover form does not.
  • On close, focus returns to the button that opened it, or to a sensible next item if that item was deleted.

Other requirements

  • Do not rely on the red confirm button alone; the label and message say the action (1.4.1).
  • The a11y report lists the outlined error trigger as contrast debt in the classic theme (1.4.3).
  • After the action completes, announce the result, such as "Document deleted", in a live region (4.1.3).
  • For legal or financial submissions, a confirmation step helps meet 3.3.4 Error Prevention.

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.

Confirmation 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 -- confirmation --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.

Confirmation package
Source css/classic/components/overlays.css
Specimens also use Box · Button · Card · Chip · Icon · Overlay · Popover · 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