Alert dialog
Stops and asks before something big, like deleting your account.
Examples
Confirm
destructivedefault
primary
States
rest
hover
focus
active
disabled
Usage
When to use it
- Use
- A destructive or irreversible action: delete a goal, discard a draft, remove a member.
- Use
- A payment above a limit, where the amount is confirmed once.
- Use
- A choice that loses unsaved work when the person leaves.
- Not for
- The dialog has fields or a task. Use Dialog.
- Not for
- The action reports a result. Show a message in the page.
- Not for
- The person can undo afterwards. Do the action and offer undo.
Rules
9 rules
- Must
- Put the safe choice first in the footer markup so focus starts there. Because focus starts on the first control, so Enter on a destructive first button deletes at once.
- Must
- Name the confirm button with the verb and noun of the trigger; never OK. Because a screen reader tabbing to "OK, button" hears nothing about deleting the goal.
- Should
- Name the other button for what it keeps, such as Keep goal, not Cancel.
- Must
- Say what is lost and where the money goes in the description. Because the description is read out when the dialog opens and is the last word before money moves.
- Never
- Title the dialog Are you sure; ask the specific question, such as Delete Vacation fund? Because the title names the dialog for a screen reader, and "Are you sure?" names no action.
- Must
- Give the footer exactly two buttons; three or fields make it a Dialog. Because the panel is the small size, built for one yes or no; more choices or a field need Dialog.
- Must
- Render AlertDialogTitle and AlertDialogDescription. Because they name and describe the panel, and without them a screen reader announces an unnamed alert dialog.
- Must
- Control open for async confirms; AlertDialogClose closes at once. Keep the dialog open on failure and show the reason in the description. Because AlertDialogClose closes before the request settles, so a failed payment vanishes with the dialog.
- Must
- Render the trigger and close parts as a Button with
render={<Button/>}. Because the parts render a bare button with none of the Button sizes, focus ring or glow.
Accessibility
4 checks
- The panel has role alertdialog, named by the title and described by the description.
- Focus moves to the first button and returns to the trigger on close.
- Escape closes without confirming; a press on the scrim does nothing.
- Tab wraps between the two buttons.
Edge cases
6 edge cases
- Long goal name
- The title wraps; a long unbroken name overflows. Truncate it yourself.
- 320px phone
- The panel is 288px and the footer stacks with the confirm button on top.
- Right to left
- Padding and position use logical properties; the footer row reverses.
- Reduced motion
- The panel appears and leaves at once.
- Opened from a menu
- Open it after the menu item closes the menu.
- Forced colors
- The panel edge relies on fill and shadow; add a transparent border.
API
4 props
AlertDialogBase UI Root propsAlertDialogTriggerBase UI propsAlertDialogContentBase UI Popup propsAlertDialogCloseBase UI props
Tokens
16 tokens
--raised- #ffffff
--radius-sheet- 24px
--shadow-overlay- 0 24px 48px -12px rgb(var(--shadow-ink) / 0.24), 0 4px 12px rgb(var(--shadow-ink) / 0.08)
--overlay-sm- 384px
--scrim- rgb(15 15 13 / 0.5)
--text-xl- 22px
--text-sm- 14px
--fg-2- #4a4943
--danger- #d93636
--danger-hover- #c02c2c
--on-danger- #ffffff
--dur-slow- 280ms
--dur-fast- 140ms
--ease-out- cubic-bezier(0.16, 1, 0.3, 1)
--ease-in- cubic-bezier(0.4, 0, 1, 1)
--scale-enter- 0.97