Overlays/Alert Dialog

Alert Dialog

A modal dialog that interrupts the user with important content.

Themed

When to Use

Use Alert Dialog when you need to:

Confirm a destructive action like deleting data or removing an account
Interrupt the user with critical information that requires acknowledgment
Force a deliberate choice before proceeding (no dismiss by clicking outside)
Present irreversible actions that need explicit Cancel or Confirm
Show system-level warnings that the user must read before continuing

When Not to Use

Non-critical confirmations - use Dialog which can be dismissed freely
Informational messages - use Alert for inline, non-blocking notices
Side panel forms or content - use Sheet for slide-out panels
Temporary notifications - use Sonner for auto-dismissing toasts

Default

Standard confirmation dialog with Cancel and Continue actions.

Destructive

Alert dialog styled for dangerous or irreversible actions like account deletion.

UX & Design Guidelines

Copy & Tone

Write clear, specific titles that state the action (“Delete this project?” not “Are you sure?”). The description should explain the consequence in plain language. Label the action button with a verb that matches the title (“Delete”, “Remove”, “Discard”) rather than generic “OK” or “Yes”.

Visual Hierarchy

For destructive actions, use bg-destructive with text-destructive-foreground on the action button. The cancel button uses variant="outline" by default to visually de-emphasize it relative to the primary action. Place the cancel button on the left and the action button on the right.

Responsive Behavior

The content container maxes out at sm:max-w-lg and is horizontally centered. On small screens the footer buttons stack vertically via flex-col-reverse so the cancel button appears below the action button (closer to the user’s thumb). The title and description center-align on mobile and left-align on sm: breakpoint.

Color & Contrast

The overlay uses bg-black/50 to dim the background and draw focus to the content panel. The content panel uses bg-background with a border and shadow-lg for clear separation. The description text uses text-muted-foreground for secondary emphasis while the title uses full text-foreground contrast.

Accessibility

Keyboard Navigation

Tab -- Cycle focus between the Cancel and Action buttons (focus is trapped inside the dialog)
Shift + Tab -- Move focus backwards through focusable elements
Enter or Space -- Activate the focused button (Cancel or Action)
Esc -- Prevented by default; the user must choose Cancel or Action explicitly

Screen Reader Support

Uses role="alertdialog" which signals an urgent, modal interruption to assistive technology
aria-labelledby is automatically linked to AlertDialogTitle
aria-describedby is automatically linked to AlertDialogDescription
Screen readers announce both the title and description when the dialog opens

Focus Management

When the dialog opens, focus moves to the AlertDialogCancel button by default (the least destructive option). Focus is trapped within the dialog content so the user cannot tab to elements behind the overlay. When the dialog closes, focus returns to the trigger element that opened it.

Overlay Interaction

Unlike Dialog, clicking the overlay does not dismiss the alert dialog. This is intentional: the user must make a deliberate choice by activating either Cancel or the Action button. This behavior ensures critical confirmations are never accidentally bypassed.

ARIA Example

{/* AlertDialog automatically sets role="alertdialog" */}
<AlertDialog>
  <AlertDialogTrigger asChild>
    <Button variant="destructive">Delete Project</Button>
  </AlertDialogTrigger>
  <AlertDialogContent>
    {/* Title is linked via aria-labelledby automatically */}
    <AlertDialogHeader>
      <AlertDialogTitle>Delete this project?</AlertDialogTitle>
      {/* Description is linked via aria-describedby automatically */}
      <AlertDialogDescription>
        All files and settings will be permanently removed.
      </AlertDialogDescription>
    </AlertDialogHeader>
    <AlertDialogFooter>
      {/* Cancel receives initial focus by default */}
      <AlertDialogCancel>Keep Project</AlertDialogCancel>
      <AlertDialogAction className="bg-destructive text-destructive-foreground">
        Delete Permanently
      </AlertDialogAction>
    </AlertDialogFooter>
  </AlertDialogContent>
</AlertDialog>

API Reference

The Alert Dialog is composed of several sub-components. Each accepts standard HTML attributes in addition to the props listed below.

AlertDialog

Prop	Type	Default	Description
open	`boolean`	—	Controlled open state of the alert dialog.
onOpenChange	`(open: boolean) => void`	—	Event handler called when the open state changes.
defaultOpen	`boolean`	false	The initial open state when uncontrolled.

AlertDialogTrigger

Prop	Type	Default	Description
asChild	`boolean`	false	Merge props onto the child element instead of rendering a default button.

AlertDialogContent

Prop	Type	Default	Description
className	`string`	—	Additional CSS classes for the content container.
onEscapeKeyDown	`(event: KeyboardEvent) => void`	—	Event handler for the Escape key. Prevented by default in alert dialogs.
onOpenAutoFocus	`(event: Event) => void`	—	Event handler called when focus moves into the content after opening.
onCloseAutoFocus	`(event: Event) => void`	—	Event handler called when focus moves back to the trigger after closing.

AlertDialogAction

Prop	Type	Default	Description
asChild	`boolean`	false	Merge props onto the child element instead of rendering a default button.
className	`string`	—	Additional CSS classes. Use to apply destructive styling.

AlertDialogCancel

Prop	Type	Default	Description
asChild	`boolean`	false	Merge props onto the child element instead of rendering a default button.
className	`string`	—	Additional CSS classes for the cancel button.