Alert Dialog

A modal dialog that interrupts the user with important content and expects a response. Built on top of Radix Dialog.

When to use

Use AlertDialog for destructive or irreversible confirmations (delete, sign out, leave without saving) where the user must explicitly acknowledge. AlertDialog blocks all background interaction. The content carries role="alertdialog", and a click on the backdrop does not close it: the user closes it through AlertDialog.Cancel, AlertDialog.Close, or the Escape key. For non-destructive input modals, use Dialog.

1import { AlertDialog } from "@ngrok/mantle/alert-dialog";2import { Button } from "@ngrok/mantle/button";3 4<AlertDialog.Root intent="info">⋯5	<AlertDialog.Trigger asChild>⋯6		<Button type="button" appearance="outlined" intent="neutral">⋯7			Show Info Alert Dialog8		</Button>9	</AlertDialog.Trigger>10	<AlertDialog.Content>⋯11		<AlertDialog.Icon />12		<AlertDialog.Body>⋯13			<AlertDialog.Header>⋯14				<AlertDialog.Title>Are you absolutely sure?</AlertDialog.Title>15				<AlertDialog.Description>⋯16					Proident quis nisi tempor irure sunt ut minim occaecat mollit sunt.17				</AlertDialog.Description>18			</AlertDialog.Header>19			<AlertDialog.Footer>⋯20				<AlertDialog.Cancel type="button">Cancel</AlertDialog.Cancel>21				<AlertDialog.Action type="button">Continue</AlertDialog.Action>22			</AlertDialog.Footer>23		</AlertDialog.Body>24	</AlertDialog.Content>25</AlertDialog.Root>;

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.

1<div className="overlay-prompt pointer-events-auto fixed inset-x-0 bottom-0 z-max">⋯2	<ConsentBanner />3</div>

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.

Composition

Compose the parts of an AlertDialog together to build your own:

AlertDialog.Root├── AlertDialog.Trigger└── AlertDialog.Content    ├── AlertDialog.Icon    └── AlertDialog.Body        ├── AlertDialog.Header        │   ├── AlertDialog.Title        │   └── AlertDialog.Description        └── AlertDialog.Footer            ├── AlertDialog.Cancel            └── AlertDialog.Action

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.

1import { AlertDialog } from "@ngrok/mantle/alert-dialog";2import { Button } from "@ngrok/mantle/button";3import { Checkbox } from "@ngrok/mantle/checkbox";4import { Choice } from "@ngrok/mantle/choice";5import { Field, toErrorMessages } from "@ngrok/mantle/field";6import { useForm } from "@tanstack/react-form";7import { useState } from "react";8import { z } from "zod";9 10const formSchema = z.object({⋯11	acknowledged: z.boolean().refine((value) => value, "Acknowledge the consequences to continue."),12});13 14function Example() {⋯15	const [open, setOpen] = useState(false);16	const form = useForm({⋯17		defaultValues: {⋯18			acknowledged: false,19		},20		validators: {⋯21			onSubmit: formSchema,22		},23		onSubmit: ({ value }) => {⋯24			// Handle the destructive action with `value`, then close the dialog25			handleOpenChange(false);26		},27	});28 29	const handleOpenChange = (nextOpen: boolean) => {⋯30		setOpen(nextOpen);31		if (!nextOpen) {⋯32			form.reset();33		}34	};35 36	return (37		<AlertDialog.Root intent="danger" open={open} onOpenChange={handleOpenChange}>⋯38			<AlertDialog.Trigger asChild>⋯39				<Button type="button" appearance="outlined" intent="danger">⋯40					Release domain41				</Button>42			</AlertDialog.Trigger>43			<AlertDialog.Content>⋯44				<AlertDialog.Icon />45				<AlertDialog.Body asChild>⋯46					<form⋯47						onSubmit={(event) => {⋯48							event.preventDefault();49							event.stopPropagation();50							void form.handleSubmit();51						}}52					>53						<AlertDialog.Header>⋯54							<AlertDialog.Title>Release this domain?</AlertDialog.Title>55							<AlertDialog.Description>⋯56								Releasing example.ngrok.app immediately removes it from your account.57							</AlertDialog.Description>58						</AlertDialog.Header>59						<form.Field name="acknowledged">⋯60							{(field) => (61								<Field.Item name={field.name}>⋯62									<Field.Control>⋯63										<Choice.Root>⋯64											<Choice.Indicator>⋯65												<Checkbox⋯66													checked={field.state.value}67													onBlur={field.handleBlur}68													onChange={(event) => field.handleChange(event.target.checked)}69												/>70											</Choice.Indicator>71											<Choice.Content>⋯72												<Choice.Label>I understand the consequences</Choice.Label>73												<Choice.Description>⋯74													Endpoints still using this domain will go offline, and the domain may be75													claimed by another account.76												</Choice.Description>77											</Choice.Content>78										</Choice.Root>79									</Field.Control>80									<Field.Errors messages={toErrorMessages(field.state.meta.errors)} />81								</Field.Item>82							)}83						</form.Field>84						<AlertDialog.Footer>⋯85							<AlertDialog.Cancel type="button">Cancel</AlertDialog.Cancel>86							<AlertDialog.Action type="submit">Release domain</AlertDialog.Action>87						</AlertDialog.Footer>88					</form>89				</AlertDialog.Body>90			</AlertDialog.Content>91		</AlertDialog.Root>92	);93}

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.

API Reference

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: