AlertDialog

A confirmation dialog for destructive or irreversible actions. Unlike Dialog, clicking outside does not dismiss it — the user must make an explicit choice. Built on @base-ui/react/alert-dialog.

Anatomy

AlertDialogContent optionally leads with AlertDialogMedia (icon area), followed by AlertDialogHeader and AlertDialogFooter. AlertDialogAction confirms the action; AlertDialogCancel dismisses. Backdrop click is intentionally disabled.

backdrop click disabledAlertDialogCancel + AlertDialogActionsize="default" | "sm"

Sizes

Two sizes available. Use size="sm" for short, one-line confirmations. Use size="default" when more context is needed.

size="default"

Best for destructive actions needing explanation.

size="sm"

Compact layout for brief confirmations.

With Media

AlertDialogMedia adds an icon area above the header — use it for high-stakes confirmations where a visual reinforces the severity.

Destructive with icon

Warning with icon

Design Guidelines

Do

  • Reserve for irreversible actions. AlertDialog signals high stakes — use it only when the action truly cannot be undone (delete, revoke, remove).
  • Label the action with its consequence. "Delete", "Remove", "Sign out" — not "OK" or "Yes".
  • Always provide a clear cancel path. AlertDialogCancel must always be present and easy to reach.

Don't

  • Don't use for informational messages. If no action is required, use Alert or Toaster — AlertDialog demands a choice.
  • Don't make the destructive action the default focus. Cancel should visually precede the action button so the safer path is reached first.
  • Don't overuse it. If every delete triggers an AlertDialog, users learn to dismiss them without reading.

Developer Reference

Accessibility

  • role="alertdialog" with aria-labelledby and aria-describedby from title and description.
  • Backdrop click is intentionally disabled — the user must use AlertDialogCancel or AlertDialogAction.
  • ESC key closes via AlertDialogCancel semantics.
  • AlertDialogMedia is decorative — icon children should use aria-hidden.
  • Focus is trapped inside; on close, focus returns to the trigger element.

Usage

import {
  AlertDialog,
  AlertDialogTrigger,
  AlertDialogContent,
  AlertDialogHeader,
  AlertDialogFooter,
  AlertDialogMedia,
  AlertDialogTitle,
  AlertDialogDescription,
  AlertDialogAction,
  AlertDialogCancel,
} from "@/components/ui/alert-dialog"
import { Trash2 } from "lucide-react"

// Basic confirmation
<AlertDialog>
  <AlertDialogTrigger asChild>
    <Button variant="destructive">Delete</Button>
  </AlertDialogTrigger>
  <AlertDialogContent>
    <AlertDialogHeader>
      <AlertDialogTitle>Delete this item?</AlertDialogTitle>
      <AlertDialogDescription>
        This action cannot be undone.
      </AlertDialogDescription>
    </AlertDialogHeader>
    <AlertDialogFooter>
      <AlertDialogCancel>Cancel</AlertDialogCancel>
      <AlertDialogAction>Delete</AlertDialogAction>
    </AlertDialogFooter>
  </AlertDialogContent>
</AlertDialog>

// With icon media
<AlertDialogContent>
  <AlertDialogMedia>
    <Trash2 aria-hidden />
  </AlertDialogMedia>
  ...
</AlertDialogContent>

// Small size
<AlertDialogContent size="sm">...</AlertDialogContent>