Alert Dialog
Ask for a deliberate decision before continuing.
Installation
pnpm dlx shadcn@4.18.0 add @siteplane/alert-dialogComplete the one-time setup first. Registry JSON lists source files and dependencies.
For this page’s examples, also install:
pnpm dlx shadcn@4.18.0 add @siteplane/alert @siteplane/button @siteplane/dialog @siteplane/form @siteplane/input @siteplane/motion @siteplane/textareaField is installed with Input.
Usage
import {
AlertDialog,
AlertDialogTrigger,
AlertDialogPopup,
AlertDialogHeader,
AlertDialogTitle,
AlertDialogDescription,
AlertDialogFooter,
AlertDialogClose,
} from "@/siteplane/components/alert-dialog";
import { Button } from "@/siteplane/components/button";
<AlertDialog>
<AlertDialogTrigger render={<Button variant="outline-destructive" />}>
Delete project
</AlertDialogTrigger>
<AlertDialogPopup>
<AlertDialogHeader>
<AlertDialogTitle>Delete project?</AlertDialogTitle>
<AlertDialogDescription>
This action can’t be undone.
</AlertDialogDescription>
</AlertDialogHeader>
<AlertDialogFooter>
<AlertDialogClose render={<Button variant="ghost" />}>
Cancel
</AlertDialogClose>
<AlertDialogClose render={<Button variant="destructive" />}>
Delete
</AlertDialogClose>
</AlertDialogFooter>
</AlertDialogPopup>
</AlertDialog>;Composition
AlertDialog
├── AlertDialogTrigger
└── AlertDialogPopup / AlertDialogContent
├── AlertDialogHeader
│ ├── AlertDialogTitle
│ └── AlertDialogDescription
└── AlertDialogFooter
└── AlertDialogCloseConfirm a request
When the confirmed action runs a request, control the root with open and onOpenChange. The destructive button shows loading while the request runs, onOpenChange ignores dismissal until it settles, and the dialog closes only after the request succeeds. If the request fails, the dialog stays open and an error Alert opens under the description in a MotionReveal, so screen readers announce it. The message closes when the person tries again, and it is gone the next time the dialog opens. The request in this example fails on the first try, so you can see the loading state, the error and the success.
Close confirmation
Control the alert dialog with open and onOpenChange to confirm before a dialog with unsaved input closes. While the comment has text, the parent dialog’s onOpenChange opens the confirmation instead of closing.
API reference
| Prop | Type | Default | Description |
|---|---|---|---|
Alert | "xs" | "sm" | "md" | "lg" | sm | Popup width from 640 px up: 400, 440, 600 or 880 px. Below 640 px the popup is a full-width sheet at the bottom edge. |
Alert | AlertDialogPrimitive.Portal.Props | unset | Portal container/mount options. |
open / default | boolean | false | Controlled or initial open state. |
on | (open, eventDetails) => void | unset | Opening/dismissal callback. |
on | (open) => void | unset | After open/close motion completes. |
AlertDialog and AlertDialogPortal are direct foundation exports. Trigger and
Close wrap the foundation action parts. Popup includes Portal, Backdrop,
Viewport and portal scope automatically; do not wrap it in another portal.
Header/Footer are div layouts that accept render, as in Dialog. Title and
Description supply accessible dialog naming. AlertDialogContent and
AlertDialogOverlay are the shadcn names of AlertDialogPopup and
AlertDialogBackdrop; both keep working. AlertDialogCreateHandle creates
detached-trigger handles; AlertDialogPrimitive exposes the namespace.
The size scale is the one Dialog and the Modal Block use. A max-w-* class in the popup's className still sets its own width, also below 640 px.
Backdrop/Viewport and the styled parts accept string className; all remaining props and refs follow Base UI Alert Dialog. Popup initialFocus/finalFocus control focus; default behavior belongs to the foundation. There is no built-in confirm callback or async loading API; Confirm a request shows how to compose one.
AlertDialogBackdrop and AlertDialogViewport wrap their matching Base UI parts with the shared overlay backdrop and centered viewport styles. They accept the foundation props and string className. AlertDialogPopup already includes both; use them separately only when composing from the primitive popup.
Usage notes
Focus is contained while open and restored on close. Provide a clear cancel action, and use Alert Dialog only for a decision the user must make before going on. For asynchronous confirmation, keep the root controlled and close only after success, as in Confirm a request; show an error message when the request fails.