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.

import { Dialog } from "@ngrok/mantle/dialog";
import { Button } from "@ngrok/mantle/button";

<Dialog.Root>
	<Dialog.Trigger asChild>
		<Button type="button">Open dialog</Button>
	</Dialog.Trigger>
	<Dialog.Content>
		<Dialog.Header>
			<Dialog.Title>Are you absolutely sure?</Dialog.Title>
			<Dialog.CloseIconButton />
		</Dialog.Header>
		<Dialog.Body>
			This action cannot be undone. This will permanently delete your account and remove your data
			from our servers.
		</Dialog.Body>
		<Dialog.Footer>
			<Dialog.Close asChild>
				<Button type="button" priority="danger" appearance="filled">
					Delete
				</Button>
			</Dialog.Close>
			<Dialog.Close asChild>
				<Button type="button" priority="neutral" appearance="outlined">
					Cancel
				</Button>
			</Dialog.Close>
		</Dialog.Footer>
	</Dialog.Content>
</Dialog.Root>;

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:

import { Dialog, isDialogOverlayTarget } from "@ngrok/mantle/dialog";

<Dialog.Content
	onPointerDownOutside={(event) => {
		// Allow closing only when clicking the actual overlay backdrop,
		// not browser autofill/password-manager popups
		if (isDialogOverlayTarget(event.target)) {
			return;
		}
		event.preventDefault();
	}}
>
	{/* dialog content with form inputs */}
</Dialog.Content>;

Composition

In some cases, you might wish to have a tooltip over the dialog trigger. This is helpful if the dialog trigger is an IconButton and you wish to provide more context to what the button does. You can compose them both together to where the dialog trigger is also the tooltip trigger.

import { Dialog } from "@ngrok/mantle/dialog";
import { Button, IconButton } from "@ngrok/mantle/button";
import { Tooltip } from "@ngrok/mantle/tooltip";
import { TrashSimpleIcon } from "@phosphor-icons/react/TrashSimple";

<Dialog.Root>
	<Tooltip.Root>
		<Tooltip.Trigger asChild>
			<Dialog.Trigger asChild>
				<IconButton type="button" label="Delete" size="sm" icon={<TrashSimpleIcon />} />
			</Dialog.Trigger>
		</Tooltip.Trigger>
		<Tooltip.Content>
			<p>Delete</p>
		</Tooltip.Content>
	</Tooltip.Root>
	<Dialog.Content>
		<Dialog.Header>
			<Dialog.Title>Are you absolutely sure?</Dialog.Title>
			<Dialog.CloseIconButton />
		</Dialog.Header>
		<Dialog.Body>
			This action cannot be undone. This will permanently delete your account and remove your data
			from our servers.
		</Dialog.Body>
		<Dialog.Footer>
			<Dialog.Close asChild>
				<Button type="button" priority="danger" appearance="filled">
					Delete
				</Button>
			</Dialog.Close>
			<Dialog.Close asChild>
				<Button type="button" priority="neutral" appearance="outlined">
					Cancel
				</Button>
			</Dialog.Close>
		</Dialog.Footer>
	</Dialog.Content>
</Dialog.Root>;

API Reference

Dialog.Root

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

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.

Prop	Type	Default	Description
`preferredWidth?`	`max-w-${string}`	`"max-w-lg"`	The preferred width of the dialog content as a Tailwind `max-w-` class. Controls the maximum width of the dialog.
`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`.

Dialog.Header

Contains the header content of the dialog, including the title and close button.

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

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?`	`"sm"` \| `"md"` \| `"lg"`	`"md"`	The size of the close icon button.
`label?`	`string`	`"Close Dialog"`	The accessible label for the close button. Important for screen readers.
`appearance?`	`"ghost"` \| `"outlined"`	`"ghost"`	The visual appearance of the close icon button.