Alert Dialog
A modal that interrupts to force an explicit confirm/cancel decision.
@garn/ui/alert-dialogDefault
Destructive delete confirmation.
Installation
garn is copy-in — the garn CLI writes this component's source into your project, so you own and can edit it. It resolves any base files and installs the npm dependencies below for you.
npx garn-ui add alert-dialog- Registry
alert-dialog- Source
- alert-dialog.tsx
- Deps
@radix-ui/react-alert-dialog- Registry deps
buttonutils
Import
import { AlertDialog } from "@garn/ui/alert-dialog";Props
Generated from the component's TypeScript types.
No component-specific props — this is a thin wrapper over its native element.
Styling
Target these data-slots and remap these tokens to restyle without forking the component.
[data-slot="alert-dialog-content"]| Property | Token | Tier |
|---|---|---|
padding | --garn-pad-surface | semantic · air |
gap | --garn-gap-stack | semantic · air |
headerGap | --garn-gap-field | semantic · air |
motion | --garn-motion-fast | semantic |
Overview
AlertDialog forces an explicit decision before continuing — confirming a destructive or irreversible action like delete, discard, or sign out. Unlike Dialog, AlertDialogContent has no dismiss-X and ignores outside-click: the only way out is the AlertDialogAction (confirm) or AlertDialogCancel (which takes initial focus). Use it sparingly, only when proceeding has real consequences; for a routine form or message, a Dialog is right, and for a non-blocking confirmation a Sonner toast with Undo is often kinder.
Guidelines
Reserve it for consequential, irreversible actions. If the action is easily undone, prefer an optimistic update with an Undo toast over interrupting the user. Overusing alert dialogs for harmless steps trains people to confirm on reflex.
Name the consequence, not the mechanism. The Title + Description should state what will happen ("Delete 3 files? This can't be undone"), and the action button should name the act ("Delete", not "OK"). Match the button's tone to the risk — destructive confirms read as danger.
Make Cancel the safe default. Initial focus lands on Cancel and Escape cancels, so an accidental Enter never destroys anything. Keep the choice binary and the copy short — this is a decision point, not a place for extra fields.
Best practices
- Always include an AlertDialogTitle and an AlertDialogDescription that states the consequence.
- Use AlertDialogAction for the confirm and AlertDialogCancel for the safe out; let Cancel keep initial focus.
- Style a destructive confirm's Action with the destructive intent.
- Don't use an alert-dialog for ordinary, non-destructive tasks — that's a dialog.
- Don't make Escape or overlay-click silently confirm — closing must be Cancel-safe.
- Don't omit the description; 'Are you sure?' alone doesn't state the stakes.
Content guidelines
- Title the decision, not the question — “Delete 3 files?” rather than “Are you sure?”.
- Use the description to state the consequence and whether it can be undone.
- Label the confirm button with the action (“Delete”), never “Yes” / “OK”.
Accessibility
- Role
alertdialog- ARIA APG
- alertdialog
- Focus
- Focus trapped inside the content, initially on Cancel; returns to the trigger on close.
Enforceable contracts
Every AlertDialogContent must contain an AlertDialogTitle (wrap it in sr-only to hide it visually).
when AlertDialogContent has no AlertDialogTitle
Keyboard
| Escape | Cancel and close (treated as the Cancel action). |
| TabShift+Tab | Cycle focus within the dialog (focus is trapped). |
| Enter | Activate the focused action button. |
- • role=alertdialog + aria-modal; labelled by AlertDialogTitle and described by AlertDialogDescription.
- • Initial focus lands on Cancel; focus returns to the trigger on close.
- • Unlike dialog, clicking the overlay does NOT dismiss it — the choice is explicit.
- Status
- Stable
- Version
v0.3.0- Introduced
v0.1.0
garn doesn't yet record a per-release version history. This reflects the component's current lifecycle state; full changelog entries will appear once the metadata pipeline emits a lifecycle.history field.