Dialog

A window overlaid on either the primary window or another dialog window, rendering the content underneath inert. Built on top of Radix UI Dialog.

When to use

Use Dialog for a centered modal that interrupts the user to gather input or confirm a non-destructive choice. For destructive confirmations (delete, irreversible actions), use AlertDialog. For side-panel content (filter panels, detail/inspector views, navigation drawers), use Sheet.

1import { Dialog } from "@ngrok/mantle/dialog";2import { Button } from "@ngrok/mantle/button";3 4<Dialog.Root>⋯5	<Dialog.Trigger asChild>⋯6		<Button type="button" appearance="filled" intent="neutral">⋯7			Open dialog8		</Button>9	</Dialog.Trigger>10	<Dialog.Content>⋯11		<Dialog.Header>⋯12			<Dialog.Title>Are you absolutely sure?</Dialog.Title>13			<Dialog.CloseIconButton />14		</Dialog.Header>15		<Dialog.Body>⋯16			This action cannot be undone. This will permanently delete your account and remove your data17			from our servers.18		</Dialog.Body>19		<Dialog.Footer>⋯20			<Dialog.Close asChild>⋯21				<Button type="button" intent="neutral" appearance="outlined">⋯22					Cancel23				</Button>24			</Dialog.Close>25			<Dialog.Close asChild>⋯26				<Button type="button" intent="danger" appearance="filled">⋯27					Delete28				</Button>29			</Dialog.Close>30		</Dialog.Footer>31	</Dialog.Content>32</Dialog.Root>;

Layering and z-index

Dialog.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="dialog-positioner") and paint above the content. When multiple overlays are open, the most recently mounted overlay renders on top.

Dialog, Sheet, and AlertDialog each render their own backdrop, so stacking modal layers compounds the dim and blur effect on the layers underneath.

UI above an open dialog

UI that must take clicks above an open 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 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 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 dialog content.

Handling autofill overlays

When a dialog contains form inputs, browser autofill or password-manager plugins (e.g. 1Password) may render overlays as siblings to the dialog content. By default, clicking these overlays triggers onPointerDownOutside, which closes the dialog. Use isDialogOverlayTarget to prevent this:

1import { Dialog, isDialogOverlayTarget } from "@ngrok/mantle/dialog";2 3<Dialog.Content⋯4	onPointerDownOutside={(event) => {⋯5		// Allow closing only when clicking the actual overlay backdrop,6		// not browser autofill/password-manager popups7		if (isDialogOverlayTarget(event.target)) {⋯8			return;9		}10		event.preventDefault();11	}}12>13	{/* dialog content with form inputs */}14</Dialog.Content>;

Composition

Compose the parts of a Dialog together to build your own:

Dialog.Root├── Dialog.Trigger└── Dialog.Content    ├── Dialog.Header    │   ├── Dialog.Title    │   ├── Dialog.Description    │   └── Dialog.CloseIconButton    ├── Dialog.Body    └── Dialog.Footer        └── Dialog.Close

Header with a description

Dialog.Title and Dialog.Description stack in a column inside Dialog.Header. Every other child shares the title's row. A long title truncates beside Dialog.CloseIconButton, and the description wraps under both.

The first dialog pairs a short title with a long description. The second pairs a long title with a one-line description in a wider dialog. In both, the title keeps its width and the description sits under it.

1import { Button } from "@ngrok/mantle/button";2import { Code } from "@ngrok/mantle/code";3import { Dialog } from "@ngrok/mantle/dialog";4 5<Dialog.Root>⋯6	<Dialog.Trigger asChild>⋯7		<Button type="button" appearance="filled" intent="neutral">⋯8			Decommission a runner9		</Button>10	</Dialog.Trigger>11	<Dialog.Content>⋯12		<Dialog.Header>⋯13			<Dialog.Title>Request decommission?</Dialog.Title>14			<Dialog.Description>⋯15				<Code>runner-ecs-us-east-1-7f3a9c</Code> drains before it leaves the pool. It keeps its16				assigned replicas until it acknowledges the request, then the scheduler removes it.17			</Dialog.Description>18			<Dialog.CloseIconButton />19		</Dialog.Header>20		<Dialog.Body>⋯21			<p>⋯22				Queued work on this runner finishes first. New work goes to the other runners in the pool.23			</p>24		</Dialog.Body>25		<Dialog.Footer>⋯26			<Dialog.Close asChild>⋯27				<Button type="button" appearance="outlined" intent="neutral">⋯28					Cancel29				</Button>30			</Dialog.Close>31			<Dialog.Close asChild>⋯32				<Button type="button" appearance="filled" intent="danger">⋯33					Request decommission34				</Button>35			</Dialog.Close>36		</Dialog.Footer>37	</Dialog.Content>38</Dialog.Root>;39 40<Dialog.Root>⋯41	<Dialog.Trigger asChild>⋯42		<Button type="button" appearance="outlined" intent="neutral">⋯43			Rotate a signing key44		</Button>45	</Dialog.Trigger>46	<Dialog.Content preferredWidth="max-w-3xl">⋯47		<Dialog.Header>⋯48			<Dialog.Title>⋯49				Rotate the signing key for every endpoint on the staging cluster and revoke the current key50				after the next deploy?51			</Dialog.Title>52			<Dialog.Description>⋯53				Connected clients re-authenticate on their next request.54			</Dialog.Description>55			<Dialog.CloseIconButton />56		</Dialog.Header>57		<Dialog.Body>⋯58			<p>The current key stays valid for one hour after the rotation.</p>59		</Dialog.Body>60		<Dialog.Footer>⋯61			<Dialog.Close asChild>⋯62				<Button type="button" appearance="outlined" intent="neutral">⋯63					Cancel64				</Button>65			</Dialog.Close>66			<Dialog.Close asChild>⋯67				<Button type="button" appearance="filled" intent="neutral">⋯68					Rotate key69				</Button>70			</Dialog.Close>71		</Dialog.Footer>72	</Dialog.Content>73</Dialog.Root>;

Full-page dialog

Every dialog already sits 16px from each viewport edge: Dialog.Content positions itself inside a fixed inset-4 wrapper, so you never add that margin yourself. appearance decides how much of the box it claims from there:

`appearance`	Width	Viewport inset	Corners and border
`"centered"`	capped at `preferredWidth`	16px	rounded and bordered
`"full-page"`	fills the box	16px	rounded and bordered
`"full-bleed"`	fills the box	none	square, no border

The three values move together as one decision, because a dialog that fills the viewport has no width left to cap and no corner left to round. preferredWidth therefore belongs to "centered" only: passing it beside "full-page" or "full-bleed" is a type error, not a prop that silently does nothing.

1// a card, capped — the default2<Dialog.Content preferredWidth="max-w-2xl">3 4// fills the 16px-inset box, still a rounded card5<Dialog.Content appearance="full-page">6 7// fills the whole viewport, square and unbordered8<Dialog.Content appearance="full-bleed">

The parts keep their roles at every appearance. Because Dialog.Content is a flex column with Dialog.Body at flex-1 overflow-y-auto, the header and footer stay pinned while the body scrolls.

When the content needs the whole viewport, reach for this: a request log, a diff, a media preview, a multi-column editor. When the content deserves its own URL, a back button, or a shareable link, a route beats a dialog.

"full-bleed" keeps its backdrop. The content opens at zoom-in-95, so a sliver of viewport edge stays uncovered for the length of the animation, and the overlay is what fills it.

The switch in the demo body swaps "full-page" for "full-bleed".

1import { Badge } from "@ngrok/mantle/badge";2import { Button } from "@ngrok/mantle/button";3import { Dialog } from "@ngrok/mantle/dialog";4import { Field } from "@ngrok/mantle/field";5import { Switch } from "@ngrok/mantle/switch";6import { useState } from "react";7 8const sampleRequests = [⋯9	{ method: "GET", path: "/api/v2/endpoints", status: 200, durationMs: 12 },10	{ method: "POST", path: "/api/v2/tunnels", status: 201, durationMs: 84 },11	{ method: "GET", path: "/api/v2/reserved_domains", status: 200, durationMs: 21 },12	{ method: "DELETE", path: "/api/v2/endpoints/ep_2f8c1a", status: 204, durationMs: 33 },13	{ method: "GET", path: "/api/v2/edges/https/edghts_1x9d", status: 502, durationMs: 1204 },14	{ method: "PATCH", path: "/api/v2/api_keys/ak_71bd", status: 200, durationMs: 47 },15];16 17// The sample repeats so the log overflows `Dialog.Body` at full height.18const requestLog = Array.from({ length: 7 })19	.flatMap(() => sampleRequests)20	.map((request, index) => ({ ...request, id: `req_${4200 + index}` }));21 22function RequestLogDialog() {⋯23	const [fullBleed, setFullBleed] = useState(false);24 25	return (26		<Dialog.Root>⋯27			<Dialog.Trigger asChild>⋯28				<Button type="button" appearance="filled" intent="neutral">⋯29					Open full-page dialog30				</Button>31			</Dialog.Trigger>32			<Dialog.Content appearance={fullBleed ? "full-bleed" : "full-page"}>⋯33				<Dialog.Header>⋯34					<Dialog.Title>Request log</Dialog.Title>35					<Dialog.CloseIconButton />36				</Dialog.Header>37				<Dialog.Body className="p-0">⋯38					<div className="border-dialog-muted bg-dialog sticky top-0 border-b px-6 py-3">⋯39						<Field.Item name="fullBleed">⋯40							<Field.Label className="flex items-center gap-2">⋯41								<Field.Control>⋯42									<Switch checked={fullBleed} onCheckedChange={setFullBleed} />43								</Field.Control>44								Full bleed45							</Field.Label>46						</Field.Item>47					</div>48					<div className="divide-card-muted divide-y font-mono text-sm">⋯49						{requestLog.map((request) => (50							<div⋯51								key={request.id}52								className="grid grid-cols-[auto_1fr_auto_auto] items-center gap-3 px-4 py-2 sm:px-6"53							>54								<span className="text-muted">{request.method}</span>55								<span className="text-strong truncate">{request.path}</span>56								<Badge appearance="muted" color={request.status >= 500 ? "danger" : "success"}>⋯57									{request.status}58								</Badge>59								<span className="text-muted text-right">{request.durationMs}ms</span>60							</div>61						))}62					</div>63				</Dialog.Body>64				<Dialog.Footer>⋯65					<Dialog.Close asChild>⋯66						<Button type="button" appearance="outlined" intent="neutral">⋯67							Close68						</Button>69					</Dialog.Close>70				</Dialog.Footer>71			</Dialog.Content>72		</Dialog.Root>73	);74}

In some cases, you might wish to have a tooltip over the dialog trigger. If the dialog trigger is an IconButton, a tooltip adds context about what the button does. Compose the two so the dialog trigger is also the tooltip trigger.

1import { Dialog } from "@ngrok/mantle/dialog";2import { Button, IconButton } from "@ngrok/mantle/button";3import { Tooltip } from "@ngrok/mantle/tooltip";4import { TrashSimpleIcon } from "@phosphor-icons/react/TrashSimple";5 6<Dialog.Root>⋯7	<Tooltip.Root>⋯8		<Tooltip.Trigger asChild>⋯9			<Dialog.Trigger asChild>⋯10				<IconButton⋯11					type="button"12					appearance="outlined"13					intent="neutral"14					label="Delete"15					size="sm"16					icon={<TrashSimpleIcon />}17				/>18			</Dialog.Trigger>19		</Tooltip.Trigger>20		<Tooltip.Content>⋯21			<p>Delete</p>22		</Tooltip.Content>23	</Tooltip.Root>24	<Dialog.Content>⋯25		<Dialog.Header>⋯26			<Dialog.Title>Are you absolutely sure?</Dialog.Title>27			<Dialog.CloseIconButton />28		</Dialog.Header>29		<Dialog.Body>⋯30			This action cannot be undone. This will permanently delete your account and remove your data31			from our servers.32		</Dialog.Body>33		<Dialog.Footer>⋯34			<Dialog.Close asChild>⋯35				<Button type="button" intent="neutral" appearance="outlined">⋯36					Cancel37				</Button>38			</Dialog.Close>39			<Dialog.Close asChild>⋯40				<Button type="button" intent="danger" appearance="filled">⋯41					Delete42				</Button>43			</Dialog.Close>44		</Dialog.Footer>45	</Dialog.Content>46</Dialog.Root>;

Stacking a Sheet over a Dialog

Dialog and Sheet share the overlay tier (z-60), so the most recently mounted overlay renders on top. Open the dialog below first, then open the sheet from inside it: the sheet stacks over the dialog rather than disappearing behind it. Each overlay renders its own backdrop, so the dialog beneath is dimmed by the sheet's overlay.

1import { Dialog } from "@ngrok/mantle/dialog";2import { Sheet } from "@ngrok/mantle/sheet";3import { Button } from "@ngrok/mantle/button";4 5<Dialog.Root>⋯6	<Dialog.Trigger asChild>⋯7		<Button type="button" appearance="filled" intent="neutral">⋯8			Open dialog9		</Button>10	</Dialog.Trigger>11	<Dialog.Content>⋯12		<Dialog.Header>⋯13			<Dialog.Title>Dialog</Dialog.Title>14			<Dialog.CloseIconButton />15		</Dialog.Header>16		<Dialog.Body className="space-y-4">⋯17			<p>Open the sheet below — it stacks on top of this dialog.</p>18			<Sheet.Root>⋯19				<Sheet.Trigger asChild>⋯20					<Button type="button" appearance="outlined" intent="neutral">⋯21						Open sheet22					</Button>23				</Sheet.Trigger>24				<Sheet.Content>⋯25					<Sheet.Header>⋯26						<Sheet.TitleGroup>⋯27							<Sheet.Title>Sheet over a dialog</Sheet.Title>28							<Sheet.Actions>⋯29								<Sheet.CloseIconButton />30							</Sheet.Actions>31						</Sheet.TitleGroup>32						<Sheet.Description>⋯33							This sheet renders on top of the dialog that opened it.34						</Sheet.Description>35					</Sheet.Header>36					<Sheet.Body>⋯37						<p>Close this sheet to return to the dialog underneath.</p>38					</Sheet.Body>39					<Sheet.Footer>⋯40						<Sheet.Close asChild>⋯41							<Button type="button" appearance="outlined" intent="neutral">⋯42								Close43							</Button>44						</Sheet.Close>45					</Sheet.Footer>46				</Sheet.Content>47			</Sheet.Root>48		</Dialog.Body>49		<Dialog.Footer>⋯50			<Dialog.Close asChild>⋯51				<Button type="button" appearance="outlined" intent="neutral">⋯52					Close53				</Button>54			</Dialog.Close>55		</Dialog.Footer>56	</Dialog.Content>57</Dialog.Root>;

With TanStack Form

Use TanStack Form with Field to gather validated input in a dialog. Dialog.Content is a flex column, so wrap Dialog.Body and Dialog.Footer in a display: contents form: the footer's submit button participates in the form while the body keeps its scrollable layout. Close the dialog from the form's onSubmit (it only runs once validation passes) and reset the form when the dialog closes so a cancelled draft doesn't leak into the next open. The form sets noValidate so the browser's native type="email" validation doesn't block the submit event: the schema owns validation and errors render consistently through Field.Errors.

If password managers or browser autofill overlays interfere with outside-click dismissal, see Handling autofill overlays.

1import { Button } from "@ngrok/mantle/button";2import { Dialog } from "@ngrok/mantle/dialog";3import { Field, toErrorMessages } from "@ngrok/mantle/field";4import { Input } from "@ngrok/mantle/input";5import { Select } from "@ngrok/mantle/select";6import { useForm } from "@tanstack/react-form";7import { useState } from "react";8import { z } from "zod";9 10const formSchema = z.object({⋯11	email: z.email("Enter a valid email address."),12	role: z.string().min(1, "Choose a role."),13});14 15function Example() {⋯16	const [open, setOpen] = useState(false);17	const form = useForm({⋯18		defaultValues: {⋯19			email: "",20			role: "",21		},22		validators: {⋯23			onSubmit: formSchema,24		},25		onSubmit: ({ value }) => {⋯26			// Handle the invite with `value`, then close the dialog27			handleOpenChange(false);28		},29	});30 31	const handleOpenChange = (nextOpen: boolean) => {⋯32		setOpen(nextOpen);33		if (!nextOpen) {⋯34			form.reset();35		}36	};37 38	return (39		<Dialog.Root open={open} onOpenChange={handleOpenChange}>⋯40			<Dialog.Trigger asChild>⋯41				<Button type="button" appearance="filled" intent="neutral">⋯42					Invite a teammate43				</Button>44			</Dialog.Trigger>45			<Dialog.Content>⋯46				<Dialog.Header>⋯47					<Dialog.Title>Invite a teammate</Dialog.Title>48					<Dialog.CloseIconButton />49				</Dialog.Header>50				<form⋯51					className="contents"52					noValidate53					onSubmit={(event) => {⋯54						event.preventDefault();55						event.stopPropagation();56						void form.handleSubmit();57					}}58				>59					<Dialog.Body className="space-y-4">⋯60						<form.Field name="email">⋯61							{(field) => (62								<Field.Item name={field.name}>⋯63									<Field.Label>Email</Field.Label>64									<Field.Control>⋯65										<Input⋯66											type="email"67											placeholder="teammate@example.com"68											value={field.state.value}69											onBlur={field.handleBlur}70											onChange={(event) => field.handleChange(event.target.value)}71										/>72									</Field.Control>73									<Field.Errors messages={toErrorMessages(field.state.meta.errors)} />74								</Field.Item>75							)}76						</form.Field>77						<form.Field name="role">⋯78							{(field) => (79								<Field.Item name={field.name}>⋯80									<Field.Label>Role</Field.Label>81									<Field.Control>⋯82										<Select.Root⋯83											value={field.state.value}84											onBlur={field.handleBlur}85											onValueChange={field.handleChange}86										>87											<Select.Trigger>⋯88												<Select.Value placeholder="Select a role" />89											</Select.Trigger>90											<Select.Content width="trigger">⋯91												<Select.Item value="admin">Admin</Select.Item>92												<Select.Item value="developer">Developer</Select.Item>93												<Select.Item value="read-only">Read-only</Select.Item>94											</Select.Content>95										</Select.Root>96									</Field.Control>97									<Field.Errors messages={toErrorMessages(field.state.meta.errors)} />98								</Field.Item>99							)}100						</form.Field>101					</Dialog.Body>102					<Dialog.Footer>⋯103						<Dialog.Close asChild>⋯104							<Button type="button" appearance="outlined" intent="neutral">⋯105								Cancel106							</Button>107						</Dialog.Close>108						<Button type="submit" appearance="filled" intent="neutral">⋯109							Send invite110						</Button>111					</Dialog.Footer>112				</form>113			</Dialog.Content>114		</Dialog.Root>115	);116}

Polymorphism

Dialog.Trigger, Dialog.Close, Dialog.Overlay, Dialog.Content, Dialog.Title, Dialog.Description, and Dialog.CloseIconButton accept asChild, which renders your single child in place of the part's default element while keeping its styling and behavior.

Dialog.Trigger asChild is by far the most common: it makes your own Button open the dialog instead of nesting a button inside one. Use Dialog.Close asChild to let any element dismiss the dialog, and Dialog.Title asChild when the heading level must fit the surrounding page outline.

Dialog.Root and Dialog.Portal render no DOM of their own (Root is a state provider and Portal only relocates its children), so neither takes asChild. Dialog.Header, Dialog.Body, and Dialog.Footer are plain layout <div>s that do not currently accept it.

API Reference

Dialog.Root

The root stateful component that manages the open/closed state of the dialog.

Dialog 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="dialog-positioner") and paint above the content. When multiple overlays are open, the most recently mounted overlay renders on top.

Prop	Type	Default	Description
`open?`	`boolean`		The controlled open state of the dialog. Must be used in conjunction with `onOpenChange`.
`onOpenChange?`	`(open: boolean) => void`		Event handler called when the open state of the dialog changes.
`defaultOpen?`	`boolean`	`false`	The open state of the dialog when it is initially rendered. Use when you do not need to control its open state.
`modal?`	`boolean`	`true`	The modality of the dialog. When set to `true`, interaction with outside elements will be disabled and only dialog content will be visible to screen readers.

Dialog.Trigger

A button that opens the dialog.

Prop	Type	Default	Description
`asChild?`	`boolean`	`false`	Use the `asChild` prop to compose the trigger functionality onto your own component.

Dialog.Content

The container for the dialog content. Renders on top of the overlay and is centered in the viewport.

Dialog.Content renders inside a positioner element (data-slot="dialog-positioner") that lays out the content and receives floats portaled from inside the dialog. The full stacking contract lives at Stacking Layers.

Prop	Type	Default	Description
`appearance?`	`"centered"` \| `"full-page"` \| `"full-bleed"`	`"centered"`	How much of the viewport the dialog claims. See Full-page dialog.
`preferredWidth?`	`max-w-${string}`	`"max-w-lg"`	The maximum width of a `"centered"` dialog, as a Tailwind `max-w-` class. Accepted for `appearance="centered"` only; a filled dialog has no width to cap.
`onEscapeKeyDown?`	`(event: KeyboardEvent) => void`		Event handler called when the escape key is down. It can be prevented by calling `event.preventDefault`.
`onInteractOutside?`	`(event: Event) => void`		Event handler called when the user interacts outside the component. It can be prevented by calling `event.preventDefault`.
`onPointerDownOutside?`	`(event: PointerDownOutsideEvent) => void`		Event handler called when a pointer event starts outside the component. It can be prevented by calling `event.preventDefault`. See Handling autofill overlays.

Data Attribute	Value	Description
`data-appearance`	`"centered"` \| `"full-page"` \| `"full-bleed"`	Reflects the resolved `appearance`.
`data-state`	`"open"` \| `"closed"`	Stamped by Radix; drives the open and close animation.

Dialog.Header

Contains the title, the description, and the close button of the dialog. Dialog.Title and Dialog.Description stack in a column. Every other child shares the title's row, so a long title truncates beside Dialog.CloseIconButton. See Header with a description.

Prop	Type	Default	Description
`children`	`ReactNode`		The content to render inside the dialog header.

Dialog.Body

Contains the main content of the dialog.

Prop	Type	Default	Description
`children`	`ReactNode`		The content to render inside the dialog body.

Dialog.Footer

Contains the footer content of the dialog, including action buttons.

Prop	Type	Default	Description
`children`	`ReactNode`		The content to render inside the dialog footer. Typically contains action buttons.

Dialog.Title

An accessible name to be announced when the dialog is opened.

Prop	Type	Default	Description
`children`	`ReactNode`		The title text for the dialog.
`asChild?`	`boolean`	`false`	Use the `asChild` prop to render a custom element instead of the default heading.

Dialog.Description

An accessible description to be announced when the dialog is opened.

Prop	Type	Default	Description
`children`	`ReactNode`		The description text for the dialog. Enhances accessibility by providing additional context.
`asChild?`	`boolean`	`false`	Use the `asChild` prop to render a custom element instead of the default `div`.

Dialog.Close

A button that closes the dialog when clicked.

Prop	Type	Default	Description
`asChild?`	`boolean`	`false`	Use the `asChild` prop to compose the close functionality onto your own component.

Dialog.CloseIconButton

An icon button that closes the dialog when clicked.

Prop	Type	Default	Description
`size?`	`"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"`	`"md"`	The size of the close icon button.
`label?`	`string`	`"Close Dialog"`	The accessible label for the close button. Important for screen readers.
`appearance?`	`"filled"` \| `"ghost"` \| `"outlined"`	`"ghost"`	The visual appearance of the close icon button.
`intent?`	`"neutral"`	`"neutral"`	The tone of the close icon button. `IconButton` draws the neutral tone only.