Alert Dialog
FreeAsk for one decision before an action that deletes data, removes access or throws work away.
npx wunderui-cli add alert-dialogPlayground
Discard unsaved changes?
Your latest edits have not been saved.
Delete project “Northstar”?
The project, its 24 tasks and all files will be permanently deleted. This can’t be undone.
Escape or a button closes it. A click on the backdrop does nothing.
Installation
npx wunderui-cli add alert-dialogWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import {
AlertDialog,
AlertDialogAction,
AlertDialogCancel,
AlertDialogContent,
AlertDialogDescription,
AlertDialogFeedback,
AlertDialogFooter,
AlertDialogHeader,
AlertDialogIcon,
AlertDialogOverlay,
AlertDialogPortal,
AlertDialogTitle,
AlertDialogTrigger,
} from "@/components/ui/alert-dialog"Then use it:
import {
AlertDialog,
AlertDialogAction,
AlertDialogCancel,
AlertDialogContent,
AlertDialogDescription,
AlertDialogFooter,
AlertDialogHeader,
AlertDialogIcon,
AlertDialogTitle,
AlertDialogTrigger,
} from "@/components/ui/alert-dialog"
import { Button } from "@/components/ui/button"
export function DeleteProject() {
return (
<AlertDialog>
<AlertDialogTrigger render={<Button variant="destructive" />}>Delete project</AlertDialogTrigger>
<AlertDialogContent size="lg">
<AlertDialogHeader>
<AlertDialogIcon variant="destructive" />
<AlertDialogTitle>Delete project “Northstar”?</AlertDialogTitle>
<AlertDialogDescription>The project, its 24 tasks and all files will be permanently deleted. This can’t be undone.</AlertDialogDescription>
</AlertDialogHeader>
<AlertDialogFooter layout="inline">
<AlertDialogCancel>Cancel</AlertDialogCancel>
<AlertDialogAction variant="destructive">Delete project</AlertDialogAction>
</AlertDialogFooter>
</AlertDialogContent>
</AlertDialog>
)
}Expected result: You should see a Delete project button. It opens a window with a Cancel and a Delete project button; Cancel or Escape closes it.
When to use
Use Alert Dialog for
- Confirming an action that deletes data or removes access, such as deleting a project
- Leaving a screen with unsaved changes
- A consequence that needs one clear decision before it happens
Size
The window is 384 px wide by default and 440 px wide in the large size, the width of the Figma set. Use large when the text or content runs long.
Delete project “Northstar”?
The project, its 24 tasks and all files will be permanently deleted. This can’t be undone.
Delete project “Northstar”?
The project, its 24 tasks and all files will be permanently deleted. This can’t be undone.
Actions
Two actions sit in a row or in a column. A third way out, such as Save and leave, always stacks.
Discard unsaved changes?
Your latest edits have not been saved.
Discard unsaved changes?
Your latest edits have not been saved.
Discard unsaved changes?
Your latest edits have not been saved.
Content
The slot between description and actions names the object: a project, a person, a file or a count. For large deletions it can also hold a typed confirmation or an acknowledgement.
Delete project “Northstar”?
The project, its 24 tasks and all files will be permanently deleted. This can’t be undone.
Remove Daniel Okafor from this workspace?
Daniel loses access to WunderUI right away. His work stays, and you can invite him again at any time.
Delete “quarterly-report.xlsx”?
The file is removed from Northstar and from every shared folder.
Delete 12 files?
The files move to Trash. Anyone using a shared link loses access.
Delete workspace “WunderUI Studio”?
All projects in this workspace are removed. This can’t be undone.
Pause the workspace?
Active deployments stop until you resume the workspace.
States and feedback
What the window shows while the request runs, when it fails, when something needs a warning, and when a title or a name is long.
States
Delete project “Northstar”?
The project, its 24 tasks and all files will be permanently deleted. This can’t be undone.
Delete project “Northstar”?
The project, its 24 tasks and all files will be permanently deleted. This can’t be undone.
Delete project “Northstar”?
The project, its 24 tasks and all files will be permanently deleted. This can’t be undone.
Delete project “Northstar”?
The project, its 24 tasks and all files will be permanently deleted. This can’t be undone.
Delete “Quarterly planning workshop with regional leads and external partners”?
The file is removed from Northstar and from every shared folder.
Keyboard interactions
The buttons are native buttons, so the browser provides focus and activation. While the window is open the page behind it is inert.
- TaborShift+Tab
- Moves focus between the buttons and fields in the window. Focus stays inside it, wrapping from the last element to the first.
- EnterorSpace
- Presses the focused button: confirms and closes, closes. In a text field, Enter does not confirm.
- Escape
- Closes the window without confirming, like Cancel. A click on the backdrop does nothing.
Behavior and motion
What the window does with focus, state, content and motion.
- Modal
- While the window is open, the page behind it is inert and does not scroll. The window is an alert dialog named by its title and described by its description; give every window both.
- No outside dismissal
- A click on the backdrop never closes or confirms. Only a footer button or Escape does, so the decision is always explicit.
- Focus
- On open, focus moves to the first focusable element: the Cancel button, or the field if there is one (you can choose another). On close it returns to the trigger unless you send it elsewhere.
- Closing and slow actions
- Both the action and cancel buttons close the window on click. For a request that can fail, control the open state, keep the window open while it runs and close it on success.
- Long text
- The window has one shrinkable column, so a long title or file name wraps instead of widening it. With long action labels, stack the footer.
- Footer layout
- By default the footer stacks below the small breakpoint with the main action on top, and sits in a row above it. You can force either layout.
- Previews in these docs
- The window is portalled to the end of the document and fixed to the screen. The previews here draw the same window inside the card so it does not cover the page.
- Opening and closing
- The window fades in, zooms from 92 % and slides up 8 px; the backdrop fades. Closing is one step faster and zooms down to 96 %.
- Reduced motion
- With reduced motion on, zoom and slide are off and the window only fades in and out.
Anatomy
The parts the component is made of. Each one renders a you can target from CSS.
Delete project “Northstar”?
The project, its 24 tasks and all files will be permanently deleted. This can’t be undone.
- data-slot="alert-dialog"
Holds the open state. Control it yourself, or leave it uncontrolled and let the trigger and buttons handle it.
- data-slot="alert-dialog-trigger"Optional
The element that opens the window, usually the button that starts the action. Focus returns to it when the window closes.
- 1data-slot="alert-dialog-content"
The window, with its own portal and backdrop. It has no corner close button, so the footer buttons are the way out; the large size matches the 440 px Figma set.
- data-slot="alert-dialog-header"Optional
Stacks the icon, the title and the description at the top of the window.
- 2Optional
A 40 px tile with the icon above the title, in a default, warning or destructive tint. Without children it shows an alert circle, a warning triangle or a trash can.
- 3data-slot="alert-dialog-title"
Names the action and its object, like Delete project Northstar? It is the accessible name of the window.
- 4data-slot="alert-dialog-description"
Says what will be lost or cannot be undone. It is read out after the title.
- 5data-slot="alert-dialog-feedback"Optional
An announced message above the actions, as an error or warning: what failed, whether anything changed, what to do next.
- 6data-slot="alert-dialog-footer"
The row of buttons. The last button in the markup sits on the right, or on top when the footer is stacked.
- 7data-slot="alert-dialog-cancel"
Closes the window without acting. Label it with the safe choice, such as Cancel or Keep editing.
- 8data-slot="alert-dialog-action"
Confirms and closes on click. Primary by default, destructive for removals, or secondary for a third way out such as Discard changes.
- data-slot="alert-dialog-overlay"Optional
The dimmed, lightly blurred backdrop, already rendered by the content. Clicking it does nothing.
- data-slot="alert-dialog-portal"Optional
Moves the window to the end of the document. The content already uses it; you only need it for a custom window or container.
Best practices
- Do
Name the object and the loss in the title, like Delete project Northstar, and put what goes with it in the description. Don't just ask Are you sure.
- Do
Repeat the action on the confirm button and make it destructive for deletions: Delete project after Cancel, so it ends up on the right.
- Do
Label the safe choice with what it does, like Keep editing or Cancel. When the action is hard to undo, focus starts on it.
- Do
For slow or failing actions, control the open state yourself. The action button closes the window on click, so prevent that, show the failure in the feedback area and turn the button into Retry.
- Do
Ask for a typed confirmation only for large deletions that cannot be undone, with a visible label, and never together with an acknowledgement.
- Don’t
Don't confirm with window.confirm. It cannot be styled or tested, while an Alert Dialog keeps the product's look, focus handling and button labels.
- Don’t
Don't use an Alert Dialog for a form or to report that something worked. A task with fields belongs in a Dialog, and success in a toast.
- Don’t
Don't ask for confirmation on routine actions that can be undone. Do them and offer Undo; a window for everything teaches people to click through.
- Don’t
Don't rely on a click outside or a corner close button to dismiss it. Neither exists here: the footer buttons and Escape are the way out.
API reference
One table per part, in the order of the anatomy. Every part also takes the props of the Base UI part it wraps (such as , and ) and the native attributes of its element.
Holds the open state. Control it yourself, or leave it uncontrolled and let the trigger and buttons handle it.
| Prop | Type | Default | Description |
|---|---|---|---|
| open | boolean | — | Whether the dialog is currently open. |
| defaultOpen | boolean | false | Whether the dialog is initially open. To render a controlled dialog, use the prop instead. |
| onOpenChange | (open, eventDetails) => void | — | Event handler called when the alert dialog is opened or closed. |
| actionsRef | RefObject<AlertDialogRoot.Actions | null> | — | A ref to imperative actions. - : Manually unmounts the alert dialog. Call this after any externally controlled closing animation finishes. - : Closes the alert dialog imperatively when called. |
| children | ReactNode | PayloadChildRenderFunction<Payload> | — | The content of the dialog. This can be a regular React node or a render function that receives the of the active trigger. |
| defaultTriggerId | string | null | — | ID of the trigger that the dialog is associated with. This is useful in conjunction with the prop to create an initially open dialog. |
| handle | AlertDialogHandle<Payload> | — | A handle to associate the alert dialog with a trigger. If specified, allows external triggers to control the alert dialog's open state. Can be created with the AlertDialog.createHandle() method. |
| onOpenChangeComplete | (open) => void | — | Event handler called after any animations complete when the dialog is opened or closed. |
| triggerId | string | null | — | ID of the trigger that the dialog is associated with. This is useful in conjunction with the prop to create a controlled dialog. There's no need to specify this prop when the dialog is uncontrolled (that is, when the prop is… |
The element that opens the window, usually the button that starts the action. Focus returns to it when the window closes.
| Prop | Type | Default | Description |
|---|---|---|---|
| render | ReactElement | (props, state) => ReactElement | — | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a or a function that returns the element to render. |
| handle | AlertDialogHandle<Payload> | — | A handle to associate the trigger with an alert dialog. Can be created with the AlertDialog.createHandle() method. |
| id | string | — | ID of the trigger. In addition to being forwarded to the rendered element, it is also used to specify the active trigger for the dialog in controlled mode (with the DialogRoot prop). |
| nativeButton | boolean | true | Whether the component renders a native element when replacing it via the prop. Set to if the rendered element is not a button (for example, ). |
| payload | Payload | — | A payload to pass to the dialog when it is opened. |
The window, with its own portal and backdrop. It has no corner close button, so the footer buttons are the way out; the large size matches the 440 px Figma set.
| Prop | Type | Default | Description |
|---|---|---|---|
| size | "default" | "lg" | "default" | is the 440 px Figma width. |
| initialFocus | boolean | RefObject<HTMLElement | null> | (openType) => unknown | — | Determines the element to focus when the dialog is opened. By default, focus moves to the first tabbable element inside the popup, except when the dialog is opened by touch — then the popup itself is focused to avoid opening the virtual ke… |
| finalFocus | boolean | RefObject<HTMLElement | null> | (closeType) => unknown | — | Determines the element to focus when the dialog is closed. - : Do not move focus. - : Move focus based on the default behavior (trigger or previously focused element). - : Move focus to the ref element. - … |
Stacks the icon, the title and the description at the top of the window.
A 40 px tile with the icon above the title, in a default, warning or destructive tint. Without children it shows an alert circle, a warning triangle or a trash can.
| Prop | Type | Default | Description |
|---|---|---|---|
| variant | "warning" | "default" | "destructive" | "default" | The tint of the tile and its default icon: (indigo, circle-alert), (the warning triangle) or (red, trash-2). |
| icon | ReactNode | — | Replaces the default icon of the variant with your own. Use a Lucide icon. |
| children | ReactNode | — | Replaces the icon too; it wins over . |
Names the action and its object, like Delete project Northstar? It is the accessible name of the window.
Says what will be lost or cannot be undone. It is read out after the title.
An announced message above the actions, as an error or warning: what failed, whether anything changed, what to do next.
| Prop | Type | Default | Description |
|---|---|---|---|
| tone | "warning" | "error" | "error" | (red) or (yellow) for the message and its leading icon. The message is announced with . |
| icon | ReactNode | — | Replaces the leading icon; hides it. |
The row of buttons. The last button in the markup sits on the right, or on top when the footer is stacked.
| Prop | Type | Default | Description |
|---|---|---|---|
| layout | "inline" | "stacked" | — | forces one row, forces one column; omitted = stacked below , inline from up. |
Closes the window without acting. Label it with the safe choice, such as Cancel or Keep editing.
| Prop | Type | Default | Description |
|---|---|---|---|
| nativeButton | boolean | true | Whether the component renders a native element when replacing it via the prop. Set to if the rendered element is not a button (for example, ). |
Confirms and closes on click. Primary by default, destructive for removals, or secondary for a third way out such as Discard changes.
| Prop | Type | Default | Description |
|---|---|---|---|
| variant | "primary" | "destructive" | "secondary" | "primary" | is the plain button for the third action ("Discard changes", "Keep editing"); it closes the dialog like the others. |
| nativeButton | boolean | true | Whether the component renders a native element when replacing it via the prop. Set to if the rendered element is not a button (for example, ). |
The dimmed, lightly blurred backdrop, already rendered by the content. Clicking it does nothing.
| Prop | Type | Default | Description |
|---|---|---|---|
| forceRender | boolean | false | Whether the backdrop is forced to render even when nested. |
Moves the window to the end of the document. The content already uses it; you only need it for a custom window or container.
| Prop | Type | Default | Description |
|---|---|---|---|
| container | HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null | — | A parent element to render the portal element into. |
| keepMounted | boolean | false | Whether to keep the portal mounted in the DOM while the popup is hidden. |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("alert-dialog")npx wunderui-cli add alert-dialogThe full library index for assistants is at /llms.txt.