Skip to content
WunderUI

Alert Dialog

Free

Ask for one decision before an action that deletes data, removes access or throws work away.

npx wunderui-cli add alert-dialog

Playground

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

bash
npx wunderui-cli add alert-dialog

Writes the source into your project with its dependencies and, on first use, the styles - see Installation.

Then import what you need:

tsx
import {
  AlertDialog,
  AlertDialogAction,
  AlertDialogCancel,
  AlertDialogContent,
  AlertDialogDescription,
  AlertDialogFeedback,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogIcon,
  AlertDialogOverlay,
  AlertDialogPortal,
  AlertDialogTitle,
  AlertDialogTrigger,
} from "@/components/ui/alert-dialog"

Then use it:

tsx
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

Use something else for

  • Dialog for a task with fields or content to work through
  • Toast for saying that something worked, without asking for anything
  • Alert for a message that stays on the page

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.

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.

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.

Northstar24 members · Last edited Oct 28, 2026

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.

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.

TaborShiftTab
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.

  • data-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.

  • Optional

    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.

  • data-slot="alert-dialog-title"

    Names the action and its object, like Delete project Northstar? It is the accessible name of the window.

  • data-slot="alert-dialog-description"

    Says what will be lost or cannot be undone. It is read out after the title.

  • data-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.

  • data-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.

  • data-slot="alert-dialog-cancel"

    Closes the window without acting. Label it with the safe choice, such as Cancel or Keep editing.

  • data-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.

PropTypeDefaultDescription
openboolean—Whether the dialog is currently open.
defaultOpenbooleanfalseWhether 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.
actionsRefRefObject<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.
childrenReactNode | 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.
defaultTriggerIdstring | 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.
handleAlertDialogHandle<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.
triggerIdstring | 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.

PropTypeDefaultDescription
renderReactElement | (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.
handleAlertDialogHandle<Payload>—A handle to associate the trigger with an alert dialog. Can be created with the AlertDialog.createHandle() method.
idstring—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).
nativeButtonbooleantrueWhether the component renders a native element when replacing it via the prop. Set to if the rendered element is not a button (for example, ).
payloadPayload—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.

PropTypeDefaultDescription
size"default" | "lg""default" is the 440 px Figma width.
initialFocusboolean | 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…
finalFocusboolean | 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.

PropTypeDefaultDescription
variant"warning" | "default" | "destructive""default"The tint of the tile and its default icon: (indigo, circle-alert), (the warning triangle) or (red, trash-2).
iconReactNode—Replaces the default icon of the variant with your own. Use a Lucide icon.
childrenReactNode—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.

PropTypeDefaultDescription
tone"warning" | "error""error" (red) or (yellow) for the message and its leading icon. The message is announced with .
iconReactNode—Replaces the leading icon; hides it.

Closes the window without acting. Label it with the safe choice, such as Cancel or Keep editing.

PropTypeDefaultDescription
nativeButtonbooleantrueWhether 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.

PropTypeDefaultDescription
variant"primary" | "destructive" | "secondary""primary" is the plain button for the third action ("Discard changes", "Keep editing"); it closes the dialog like the others.
nativeButtonbooleantrueWhether 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.

PropTypeDefaultDescription
forceRenderbooleanfalseWhether 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.

PropTypeDefaultDescription
containerHTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null—A parent element to render the portal element into.
keepMountedbooleanfalseWhether 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.

MCPget_component("alert-dialog")
Installnpx wunderui-cli add alert-dialog

The full library index for assistants is at /llms.txt.