Alert Dialog
A modal dialog that interrupts the user with important content and expects a response. AlertDialog.Root requires an intent, which sets the color of the icon and the action.
When to use
- Confirm a destructive or irreversible action before it runs, such as a delete, a sign-out, or a leave without saving.
- Prefer
Dialogfor a modal that gathers input or confirms a choice that is not destructive. - Prefer
Sheetfor content that slides in from the edge of the screen, such as a filter panel or a detail view. - Prefer
Sandbarfor unsaved changes on the page, with a bar that waits for the user to save or discard them.
Intent
Set intent="danger" when the action destroys data or cannot be undone. Use intent="info" for every other confirmation.
Layering and z-index
AlertDialog.Content renders its floating layer at Tailwind z-60, Mantle's overlay tier, above every float (z-50). Floats composed inside the content portal into the positioner (data-slot="alert-dialog-positioner") and paint above the content. When multiple overlays are open, the most recently mounted overlay renders on top.
AlertDialog, Dialog, and Sheet each render their own backdrop, so stacking modal layers compounds the dim and blur effect on the layers underneath.
UI above an open alert dialog
UI that must take clicks above an open alert dialog, such as a consent banner, carries the overlay-prompt class. A click inside it does not count as an outside click. Add pointer-events-auto too, because the open alert dialog sets pointer-events: none on <body>. mantle's Toaster does both.
The class reaches pointer input only. The open alert dialog traps keyboard focus and hides outside content from assistive technology with aria-hidden, so a keyboard or screen reader user cannot reach the banner. Put a control that every user must reach inside the alert dialog content.
Third-party popups
A script can show its own popup in a frame on <body>, above the alert dialog. A payment script does this for a 3-D Secure challenge and for a wallet sign-in. While that frame is on top at the center of the viewport, the alert dialog yields to the popup. Focus that the script moves into the popup stays there. Escape does not close the alert dialog: it moves focus into the popup, and the popup then takes the keyboard.
Close the alert dialog from your code only after the popup closes. Third-party popups on the Sheet page has the reason, the rule for what counts as a popup, and an example.
Composition
Compose the parts of an AlertDialog together to build your own:
With TanStack Form
Compose an AlertDialog with TanStack Form and Field when the destructive action requires explicit acknowledgment. Render AlertDialog.Body as the <form> element with asChild so the header, field, and footer keep the alert dialog layout. AlertDialog.Action does not close the dialog by default: make it the submit button (type="submit") and close the dialog from the form's onSubmit, which only runs once validation passes. Control AlertDialog.Root with open / onOpenChange and reset the form on close so the acknowledgment is required every time the dialog opens.
The acknowledgment row composes Choice inside Field.Control, so the checkbox aligns to the first line of its label and the field's name and ARIA wiring flow onto the checkbox automatically.
Polymorphism
Every part of AlertDialog that renders DOM accepts asChild, which swaps the part's default element for your single child while keeping its styling, data-slot, and behavior. AlertDialog.Root is a state provider and renders no DOM, so it takes no asChild; AlertDialog.Icon already takes its element through the svg prop and clones it.
Dismissal
AlertDialog blocks all background interaction. The content carries role="alertdialog", and a click on the backdrop does not close it. The user closes it with AlertDialog.Cancel, AlertDialog.Close, or the Escape key.
API Reference
The AlertDialog components are built on top of Radix Dialog.
AlertDialog.Root
Holds the open state and the required intent that AlertDialog.Icon and AlertDialog.Action read for their color.
AlertDialog renders its floating layer at Tailwind z-60, Mantle's overlay tier, above every float (z-50). Floats composed inside the content portal into the positioner (data-slot="alert-dialog-positioner") and paint above the content. When multiple overlays are open, the most recently mounted overlay renders on top.
All props from Radix Dialog.Root, plus:
AlertDialog.Trigger
A button that opens the Alert Dialog.
Radix Dialog.Trigger props.
AlertDialog.Content
The popover Alert Dialog container. Renders on top of the overlay and is centered in the viewport.
AlertDialog.Content renders its floating layer at Tailwind z-60, Mantle's overlay tier, above every float (z-50). Floats composed inside the content portal into the positioner (data-slot="alert-dialog-positioner") and paint above the content. When multiple overlays are open, the most recently mounted overlay renders on top.
AlertDialog.Content renders inside a positioner element (data-slot="alert-dialog-positioner") that lays out the content and receives floats portaled from inside the alert dialog. The full stacking contract lives at Stacking Layers.
Radix Dialog.Content props, plus:
onInteractOutside still fires, but AlertDialog.Content calls event.preventDefault() after your handler, so an outside pointer interaction never closes the dialog.
AlertDialog.Body
Contains the main content of the alert dialog.
All props from div, plus:
AlertDialog.Header
Contains the header content of the dialog, including the title and description.
All props from div, plus:
AlertDialog.Footer
Contains the footer content of the dialog, including the action and cancel buttons.
All props from div, plus:
AlertDialog.Title
An accessible name to be announced when the dialog is opened.
Alternatively, pass aria-label or aria-labelledby to AlertDialogContent and exclude this component.
Radix Dialog.Title props.
AlertDialog.Description
An accessible description to be announced when the dialog is opened. Renders as a div by default, but can be changed to any other element using the asChild prop.
Alternatively, pass aria-describedby to AlertDialogContent and exclude this component.
Radix Dialog.Description props.
AlertDialog.Action
A button that confirms the Alert Dialog action. Defaults to appearance="filled", with a tone derived from AlertDialog.Root's intent: "danger" dialogs get a danger button, "info" dialogs get a neutral one. Does not close the alert dialog by default.
These buttons should be distinguished visually from AlertDialog.Cancel.
Composes around the mantle Button component. All Button props, except appearance and intent, which are optional here. When omitted, appearance defaults to "filled" and intent derives from the dialog's intent as described above.
AlertDialog.Cancel
A button that closes the dialog and cancels the action. Defaults to appearance="outlined" and intent="neutral".
This button should be distinguished visually from AlertDialog.Action.
Composes around the mantle Button component. All Button props, except appearance and intent, which are optional here. When omitted, they default to "outlined" and "neutral" as described above.
AlertDialog.Icon
An icon that visually represents the intent of the AlertDialog. Defaults to a warning icon for danger intent and an info icon for info intent with the appropriate color. The icon is decorative and renders aria-hidden="true" unless you name it.
All props from svg except children, plus:
AlertDialog.Close
A button that closes the dialog.
All props from button, plus: