Alert Dialog

Alert Dialog interrupts the user’s workflow to communicate critical information or confirm an action that cannot be taken lightly. It presents a short, focused message and requires the user to explicitly confirm or cancel before proceeding.

Use Alert Dialog for actions such as deleting data, performing irreversible changes, or acknowledging important warnings where dismissal without a decision would be unsafe. It is the preferred starting point for critical confirmations when the decision can be explained in a short, focused message.

Installation

npx shadcn-ui@latest add alert-dialog

<Step>Install the following dependencies:</Step>

npm install @radix-ui/react-alert-dialog

<Step>Copy and paste the following code into your project.</Step>

<Step>Update the import paths to match your project setup.</Step>

Usage

import {
  AlertDialog,
  AlertDialogAction,
  AlertDialogBody,
  AlertDialogCancel,
  AlertDialogContent,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogTitle,
  AlertDialogTrigger,
} from '@/components/ui/alert-dialog'

<AlertDialog>
  <AlertDialogTrigger>Open</AlertDialogTrigger>
  <AlertDialogContent>
    <AlertDialogHeader>
      <AlertDialogTitle>Are you absolutely sure?</AlertDialogTitle>
      <AlertDialogDescription>
        This action cannot be undone. This will permanently delete your account and remove your data
        from our servers.
      </AlertDialogDescription>
    </AlertDialogHeader>
    <AlertDialogFooter>
      <AlertDialogCancel>Cancel</AlertDialogCancel>
      <AlertDialogAction>Continue</AlertDialogAction>
    </AlertDialogFooter>
  </AlertDialogContent>
</AlertDialog>

Behavior

Unlike a generic Dialog, an Alert Dialog cannot be dismissed by clicking outside the modal. The user must take an explicit action by confirming, cancelling, or pressing Escape.

This enforced decision helps prevent accidental dismissal of critical warnings or destructive actions.

Supabase’s Alert Dialog extends the Radix/Shadcn version with async action handling. When an AlertDialogAction returns a Promise, the dialog keeps focus trapped, blocks dismissal, and shows loading until the Promise resolves. Rejected Promises keep the dialog open so consumers can render inline error feedback.

Guidelines

• Keep content concise: AlertDialogDescription renders as a single paragraph and must not contain block-level elements such as lists, multiple paragraphs, or complex layouts.
• Use for critical decisions only: Reserve Alert Dialog for destructive or irreversible actions, or for warnings that require explicit acknowledgement.
• Use for dirty-form discard confirmation: A short discard-confirmation step after a dirty form dismissal attempt (backdrop, Escape, or Cancel) is a valid Alert Dialog pattern. In Studio, prefer DiscardChangesConfirmationDialog for this flow.
• Always provide a cancel action: Include AlertDialogCancel so users can safely back out, in addition to supporting the Escape key.
• Use AlertDialogBody for inline feedback: If async actions can fail, render inline feedback such as an Admonition inside AlertDialogBody so spacing stays consistent.
• Avoid rich content: If the decision requires detailed explanations, callouts, multiple paragraphs, or form inputs, move to Confirmation Modal or Dialog instead.

See Modality for guidance on choosing the appropriate dialog pattern.

Examples

Async action

When an action returns a Promise, Alert Dialog keeps the dialog open, shows a loading state on the action button, and disables dismissal until the Promise resolves.

Async action error

Catch errors to show inline feedback, then rethrow so Alert Dialog can reset the loading state and keep the dialog open.

Close only

Warning

Destructive