OpenWikishadcn-ui/ui

Alert Dialog

Purpose and Scope

Alert Dialog is the modal confirmation pattern for moments when an application must interrupt the user with important content and wait for an explicit response. In shadcn/ui terms, it is not just a generic popover or informational callout: it is a blocking dialog for consequential actions such as deleting an account, continuing a destructive workflow, or acknowledging a decision that cannot be casually dismissed. The documentation presents the component as an installable registry item with a consistent name, shared composition vocabulary, and variants across ARIA, Base UI, and Radix-backed implementations.

Sources: apps/v4/content/docs/components/aria/alert-dialog.mdx, apps/v4/content/docs/components/base/alert-dialog.mdx, apps/v4/content/docs/components/radix/alert-dialog.mdx

The ARIA page is the primary reader-facing guide for this page because the requested implementation source is the ARIA base registry component. The neighboring Dialog and Alert docs help clarify boundaries. Dialog is the broader overlaid-window primitive that renders underlying content inert, while Alert is a non-modal callout for drawing attention without requiring a modal decision. Alert Dialog combines the seriousness of an alert with the structure and focus-management expectations of a dialog, so authors should reserve it for user decisions rather than routine status messages.

Sources: apps/v4/content/docs/components/aria/alert-dialog.mdx, apps/v4/content/docs/components/aria/dialog.mdx, apps/v4/content/docs/components/aria/alert.mdx

Relevant Source Files

  • apps/v4/content/docs/components/aria/alert-dialog.mdx - Primary ARIA Alert Dialog documentation, including installation, usage, composition, examples, RTL preview, and the size API reference.
  • apps/v4/content/docs/components/aria/alert.mdx - Related ARIA Alert documentation used to distinguish non-modal attention callouts from blocking alert dialogs.
  • apps/v4/content/docs/components/aria/dialog.mdx - Related ARIA Dialog documentation used to connect Alert Dialog behavior to modal dialog concepts and shared React Aria links.
  • apps/v4/content/docs/components/base/alert-dialog.mdx - Base UI variant documentation showing the same public component story with Base UI dependency and trigger/content composition.
  • apps/v4/content/docs/components/radix/alert-dialog.mdx - Radix variant documentation showing the same public component story with Radix dependency and asChild trigger composition.
  • apps/v4/registry/bases/aria/ui/alert-dialog.tsx - ARIA registry implementation for the exported component functions, slots, role, size handling, and React Aria primitive wiring.

Installation and Usage

Install the component through the CLI when your project already follows shadcn/ui conventions. The documented command is intentionally terse because the CLI resolves the selected registry style, copies the component source into your project, and leaves you with local code that can be customized. For manual installation in the ARIA version, the docs require react-aria-components, copying the component source into components/ui/alert-dialog.tsx, and updating import paths to match the local project aliases. Base UI and Radix variants use the same component name but different primitive packages.

Sources: apps/v4/content/docs/components/aria/alert-dialog.mdx, apps/v4/content/docs/components/base/alert-dialog.mdx, apps/v4/content/docs/components/radix/alert-dialog.mdx

npx shadcn@latest add alert-dialog

A typical ARIA usage starts by importing AlertDialog, AlertDialogTrigger, AlertDialogHeader, AlertDialogTitle, AlertDialogDescription, AlertDialogFooter, AlertDialogCancel, and AlertDialogAction from the local component file. The trigger wraps the button that opens the modal, and the AlertDialog contains the content that will be presented as an alertdialog. The example copy uses a title that asks whether the user is sure, a description explaining the irreversible outcome, and footer actions for canceling or continuing. That structure gives assistive technologies enough semantic context while keeping the visual layout predictable.

Sources: apps/v4/content/docs/components/aria/alert-dialog.mdx, apps/v4/registry/bases/aria/ui/alert-dialog.tsx

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

Composition and Variants

The documented ARIA composition places AlertDialogTrigger at the top, with a Button and AlertDialog as children. Inside the dialog, AlertDialogHeader groups optional AlertDialogMedia, AlertDialogTitle, and AlertDialogDescription; AlertDialogFooter then contains AlertDialogCancel and AlertDialogAction. That hierarchy matters because it separates disclosure, content, semantic labeling, explanatory text, and decision controls. In practice, the title should name the decision, the description should explain the consequence, and the footer should make the safer escape path easy to find.

Sources: apps/v4/content/docs/components/aria/alert-dialog.mdx, apps/v4/registry/bases/aria/ui/alert-dialog.tsx

The official examples cover a basic confirmation, a small size, media-enhanced dialogs, small dialogs with media, destructive actions, and RTL rendering. The size variant is controlled by size set to sm or default, while AlertDialogMedia is the intended slot for an icon or image that supports the message. The destructive example is described in terms of AlertDialogAction because the confirming action is the risky operation. For right-to-left interfaces, the docs point readers to the shared RTL configuration guide and include an RTL preview for the component.

Sources: apps/v4/content/docs/components/aria/alert-dialog.mdx, apps/v4/content/docs/components/base/alert-dialog.mdx, apps/v4/content/docs/components/radix/alert-dialog.mdx

AlertDialogTrigger
├── Button
└── AlertDialog
    ├── AlertDialogHeader
    │   ├── AlertDialogMedia
    │   ├── AlertDialogTitle
    │   └── AlertDialogDescription
    └── AlertDialogFooter
        ├── AlertDialogCancel
        └── AlertDialogAction

System-to-Code Mapping

The ARIA registry implementation is a client component that imports Dialog, DialogTrigger, Heading, ModalOverlay, Modal, and related prop types from react-aria-components. AlertDialogTrigger is a thin wrapper over the React Aria DialogTrigger primitive with a data-slot marker. AlertDialogOverlay wraps ModalOverlay and applies the fixed, full-screen overlay slot. AlertDialog then renders a Modal with data-slot alert-dialog-content, a data-size attribute, and an inner Dialog primitive with role set to alertdialog. This is the key behavior mapping from the docs concept to accessible modal semantics.

Sources: apps/v4/registry/bases/aria/ui/alert-dialog.tsx

The implementation also exposes layout helpers that match the documentation names. AlertDialogContent delegates to AlertDialog while preserving className and size, which gives projects a content-style API even though the ARIA usage example nests AlertDialog directly under the trigger. AlertDialogHeader, AlertDialogFooter, and AlertDialogMedia are div-based slots decorated with data-slot attributes and class names. The footer uses flex and small-size group selectors so action layout changes when data-size is sm. AlertDialogTitle renders a React Aria Heading in the title slot, and AlertDialogDescription renders a div for supporting copy.

Sources: apps/v4/registry/bases/aria/ui/alert-dialog.tsx

The Base UI and Radix docs show the same product contract with implementation-specific trigger ergonomics. Base UI installs @base-ui/react and uses AlertDialogTrigger with a render prop that renders a Button. Radix installs radix-ui and uses AlertDialogTrigger asChild around a Button. Both variants include AlertDialogContent explicitly in the public example, while the ARIA example presents AlertDialog as the content container and the implementation provides AlertDialogContent as an alias-style wrapper. When moving between bases, keep the user-facing composition and copy intact, but adjust the primitive-specific trigger pattern.

Sources: apps/v4/content/docs/components/base/alert-dialog.mdx, apps/v4/content/docs/components/radix/alert-dialog.mdx, apps/v4/content/docs/components/aria/alert-dialog.mdx, apps/v4/registry/bases/aria/ui/alert-dialog.tsx

API Reference

The documented Alert Dialog API is intentionally compact. The size prop controls the dialog content size and accepts default or sm, with default as the default value. In the ARIA implementation, size is accepted by AlertDialog and AlertDialogContent, written to data-size on the modal content, and used by slot styling such as the footer layout. AlertDialog also accepts isDismissable from the React Aria Modal primitive selection shown in the implementation type signature, while overlay-related props flow through the ModalOverlay wrapper. Other primitive behavior should be checked against the underlying React Aria Modal API.

Sources: apps/v4/content/docs/components/aria/alert-dialog.mdx, apps/v4/registry/bases/aria/ui/alert-dialog.tsx

  • AlertDialogTrigger: wraps the trigger primitive and marks the slot as alert-dialog-trigger.
  • AlertDialog: renders the overlay, modal content, and inner dialog with role alertdialog; accepts size default or sm.
  • AlertDialogContent: convenience wrapper around AlertDialog with the same component props.
  • AlertDialogHeader: structural container for media, title, and description.
  • AlertDialogMedia: optional media slot for icons or images.
  • AlertDialogTitle: title slot rendered through React Aria Heading.
  • AlertDialogDescription: supporting description container.
  • AlertDialogFooter: action area for cancel and confirm controls, with small-size layout behavior.
  • AlertDialogCancel and AlertDialogAction: button-based decision controls; the action slot is used for the continuing or destructive operation.

Implementation Guidance and Next Steps

Use Alert Dialog sparingly. If the user only needs a status message, the Alert component is the lighter fit; if the user needs a modal workflow without the urgency of a required response, Dialog is the more general pattern. When Alert Dialog is appropriate, write a title that states the decision, a description that makes the consequence explicit, and actions whose labels map to the real outcome. Prefer a clearly reversible cancel action and reserve destructive styling or copy for the action that commits the dangerous change.

Sources: apps/v4/content/docs/components/aria/alert-dialog.mdx, apps/v4/content/docs/components/aria/alert.mdx, apps/v4/content/docs/components/aria/dialog.mdx

Next, read the Dialog page for general modal behavior, the Alert page for non-modal attention callouts, and the RTL guide before shipping right-to-left layouts. If your project standardizes on Base UI or Radix instead of ARIA, compare the corresponding Alert Dialog docs before copying examples because the trigger and content wrappers differ even though the component vocabulary remains aligned.

Ask a question...