Skip to content
Nexus Application Design nadesign

AlertDialog

<AlertDialog> is a confirmation modal — interruptive, requires an explicit choice. Use only when the next action is irreversible or has a real cost. For a wired up async confirm, prefer ConfirmDialog.

import from "@na/ui/components/alert-dialog" ▶ Open in Storybook packages/ui/src/components/alert-dialog.tsx

When to use

  • Destructive actions: delete, archive, reset, kill.
  • Operations that take effect on other users (publish, unpublish).
  • Anything one click away from data loss.

Don’t use AlertDialog for: routine save / cancel (use Dialog only when needed), warnings the user can act on later (use an inline Alert), or notifications (use Sonner).

Destructive

<AlertDialog>
  <AlertDialogTrigger asChild>
    <Button variant="destructive">Delete agent</Button>
  </AlertDialogTrigger>
  <AlertDialogContent>
    <AlertDialogHeader>
      <AlertDialogTitle>Delete this agent?</AlertDialogTitle>
      <AlertDialogDescription>
        This action cannot be undone.
      </AlertDialogDescription>
    </AlertDialogHeader>
    <AlertDialogFooter>
      <AlertDialogCancel>Cancel</AlertDialogCancel>
      <AlertDialogAction className="bg-destructive text-destructive-foreground hover:bg-destructive/90">
        Delete
      </AlertDialogAction>
    </AlertDialogFooter>
  </AlertDialogContent>
</AlertDialog>

API

AlertDialog mirrors Radix AlertDialog. Required composition: AlertDialog → AlertDialogTrigger → AlertDialogContent → AlertDialogHeader → AlertDialogTitle + AlertDialogDescription → AlertDialogFooter → AlertDialogCancel + AlertDialogAction.

AlertDialogAction and AlertDialogCancel are <button>s. Style Action with bg-destructive + destructive-foreground for irreversible verbs.

Design guidelines

✓ Do

  • Lead the title with the verb in question form: "Delete this agent?"
  • Restate the consequence in the description. "This action cannot be undone."
  • Make the destructive button visually destructive (red).

✗ Don't

  • Pre-confirm with phrases like "Are you sure?". Reviewers find that condescending; the consequence sentence already makes the user think.
  • Use AlertDialog for routine actions — over-asking trains users to click through every modal.
  • Default-focus the destructive button. Cancel is the safe default.

Accessibility

  • Composes Radix AlertDialog — focus trapped, Esc closes (treated as Cancel).
  • role="alertdialog" is set automatically.
  • ConfirmDialog — Wraps AlertDialog with async + pending state.
  • ConfirmPopover — Inline (anchored) confirmation.
  • Sonner — For “deleted — Undo” pattern (often nicer than confirm-first).

▶ Open AlertDialog stories in Storybook