Dialog · ui.voila.dev

Usage

import { Dialog } from "@voila.dev/ui/dialog";

<Dialog.Root>
	<Dialog.Trigger render={<Button variant="outline" />}>Invite</Dialog.Trigger>
	<Dialog.Content>
		<Dialog.Header>
			<Dialog.Title>Invite a freelancer</Dialog.Title>
			<Dialog.Description>Send an invitation so they can…</Dialog.Description>
		</Dialog.Header>
		<Dialog.Footer>
			<Dialog.Close render={<Button variant="outline" />}>Cancel</Dialog.Close>
			<Button>Send invitation</Button>
		</Dialog.Footer>
	</Dialog.Content>
</Dialog.Root>

A modal window for a task that deserves the whole screen's attention. It traps focus and blocks the page behind it, which is the point and also the cost — use it when interrupting is correct, and something quieter when it is not. For a question with two answers, AlertDialog or ConfirmDialog already have the shape. For content that belongs beside its trigger rather than over everything, Popover. On a phone a centred modal is the wrong shape entirely — ResponsiveDialog is this component that becomes a bottom drawer under 768px.

Triggers take a render prop rather than wrapping a button, so the trigger is your button and there is no nested-button markup.

Recipes

Four widths

size changes the panel width only — padding and type scale hold, so a xl dialog is a wider dialog rather than a bigger one. Pick it from the content: a form with two columns needs lg, a confirmation needs sm.

showCloseButton and closeButtonLabel control the X in the corner. Leave the X on unless the dialog has its own explicit dismiss in the footer; a modal with no visible way out reads as a trap even when Escape works.

API

Dialog.Root

Prop	Type	Default
`actionsRef`	`RefObject<DialogRootActions \| null>`	—	A ref to imperative actions.
`children`	`PayloadChildRenderFunction<unknown> \| ReactNode`	—	The content of the dialog. This can be a regular React node or a render function that receives the `payload` of the active trigger.
`defaultOpen`	`boolean`	—	Whether the dialog is initially open. To render a controlled dialog, use the `open` prop instead.
`defaultTriggerId`	`string \| null`	—	ID of the trigger that the dialog is associated with. This is useful in conjunction with the `defaultOpen` prop to create an initially open dialog.
`disablePointerDismissal`	`boolean`	—	Whether to prevent the dialog from closing on outside presses. For non-modal dialogs, this also prevents the dialog from closing when focus moves outside of it.
`handle`	`DialogHandle<unknown>`	—	A handle to associate the dialog with a trigger. If specified, allows external triggers to control the dialog's open state. Can be created with the Dialog.createHandle() method.
`modal`	`"trap-focus" \| boolean`	—	Determines if the dialog enters a modal state when open. When `modal` is `true` or `'trap-focus'`, render `<Dialog.Close>` inside `<Dialog.Popup>` so touch screen readers can escape the popup.
`onOpenChange`	`((open: boolean, eventDetails: DialogRootChangeEventDetails) => void)`	—	Event handler called when the dialog is opened or closed.
`onOpenChangeComplete`	`((open: boolean) => void)`	—	Event handler called after any animations complete when the dialog is opened or closed.
`open`	`boolean`	—	Whether the dialog is currently open.
`triggerId`	`string \| null`	—	ID of the trigger that the dialog is associated with. This is useful in conjunction with the `open` prop to create a controlled dialog. There's no need to specify this prop when the dialog is uncontrolled (that is, when the `open` prop is not set).

Plus the DOM props of the element it renders. Source: dialog/components/dialog-root.tsx.

Dialog.Close

Prop	Type	Default
`className`	`string` \| `((state: DialogCloseState) => string` \| `undefined)`	—	CSS class applied to the element, or a function that returns a class based on the component's state.
`nativeButton`	`boolean`	—	Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`).
`render`	`ComponentRenderFn<HTMLProps, DialogCloseState>` \| `ReactElement<unknown, string \| JSXElementConstructor<any>>`	—	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
`style`	`CSSProperties` \| `((state: DialogCloseState) => CSSProperties` \| `undefined)`	—	Style applied to the element, or a function that returns a style object based on the component's state.

Plus the DOM props of the element it renders. Source: dialog/components/dialog-close.tsx.

Dialog.Content

Prop	Type	Default
`closeButtonLabel`	`string`	`"Close"`	Accessible name for that X. This package ships no translations.
`overlayClassName`	`string`	—	Classes for the backdrop behind the panel. `className` styles the panel itself.
`showCloseButton`	`boolean`	`true`	Draws the X in the corner.
`size`	`DialogContentSize`	`"sm"`	Width of the panel. Pick by the content, not by the importance of the task.
`className`	`string` \| `((state: DialogPopupState) => string` \| `undefined)`	—	CSS class applied to the element, or a function that returns a class based on the component's state.
`finalFocus`	`boolean` \| `RefObject<HTMLElement \| null>` \| `((closeType: InteractionType) => void` \| `boolean` \| `HTMLElement` \| `null)`	—	Determines the element to focus when the dialog is closed.
`initialFocus`	`boolean` \| `RefObject<HTMLElement \| null>` \| `((openType: InteractionType) => void` \| `boolean` \| `HTMLElement` \| `null)`	—	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 keyboard.
`render`	`ComponentRenderFn<HTMLProps, DialogPopupState>` \| `ReactElement<unknown, string \| JSXElementConstructor<any>>`	—	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
`style`	`CSSProperties` \| `((state: DialogPopupState) => CSSProperties` \| `undefined)`	—	Style applied to the element, or a function that returns a style object based on the component's state.

Plus the DOM props of the element it renders. Source: dialog/components/dialog-content.tsx.

Dialog.Description

Prop	Type	Default
`className`	`string` \| `((state: DialogDescriptionState) => string` \| `undefined)`	—	CSS class applied to the element, or a function that returns a class based on the component's state.
`render`	`ComponentRenderFn<HTMLProps, DialogDescriptionState>` \| `ReactElement<unknown, string \| JSXElementConstructor<any>>`	—	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
`style`	`CSSProperties` \| `((state: DialogDescriptionState) => CSSProperties` \| `undefined)`	—	Style applied to the element, or a function that returns a style object based on the component's state.

Plus the DOM props of the element it renders. Source: dialog/components/dialog-description.tsx.

Dialog.Footer

Prop	Type	Default
`closeLabel`	`string`	—	Text of the built-in dismiss button. Omit the prop to render no dismiss at all.
`render`	`ComponentRenderFn<HTMLProps, {}>` \| `ReactElement<unknown, string \| JSXElementConstructor<any>>`	—	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.

Plus every <div> prop. Source: dialog/components/dialog-footer.tsx.

Dialog.Header

Prop	Type	Default
`render`	`ComponentRenderFn<HTMLProps, {}>` \| `ReactElement<unknown, string \| JSXElementConstructor<any>>`	—	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.

Plus every <div> prop. Source: dialog/components/dialog-header.tsx.

Dialog.Overlay

Prop	Type	Default
`className`	`string` \| `((state: DialogBackdropState) => string` \| `undefined)`	—	CSS class applied to the element, or a function that returns a class based on the component's state.
`forceRender`	`boolean`	—	Whether the backdrop is forced to render even when nested.
`render`	`ComponentRenderFn<HTMLProps, DialogBackdropState>` \| `ReactElement<unknown, string \| JSXElementConstructor<any>>`	—	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
`style`	`CSSProperties` \| `((state: DialogBackdropState) => CSSProperties` \| `undefined)`	—	Style applied to the element, or a function that returns a style object based on the component's state.

Plus the DOM props of the element it renders. Source: dialog/components/dialog-overlay.tsx.

Dialog.Portal

Prop	Type	Default
`className`	`string` \| `((state: DialogPortalState) => string` \| `undefined)`	—	CSS class applied to the element, or a function that returns a class based on the component's state.
`container`	`HTMLElement` \| `RefObject<HTMLElement \| ShadowRoot \| null>` \| `ShadowRoot` \| `null`	—	A parent element to render the portal element into.
`keepMounted`	`boolean`	—	Whether to keep the portal mounted in the DOM while the popup is hidden.
`render`	`ComponentRenderFn<HTMLProps, DialogPortalState>` \| `ReactElement<unknown, string \| JSXElementConstructor<any>>`	—	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
`style`	`CSSProperties` \| `((state: DialogPortalState) => CSSProperties` \| `undefined)`	—	Style applied to the element, or a function that returns a style object based on the component's state.

Plus the DOM props of the element it renders. Source: dialog/components/dialog-portal.tsx.

Dialog.Title

Prop	Type	Default
`className`	`string` \| `((state: DialogTitleState) => string` \| `undefined)`	—	CSS class applied to the element, or a function that returns a class based on the component's state.
`render`	`ComponentRenderFn<HTMLProps, DialogTitleState>` \| `ReactElement<unknown, string \| JSXElementConstructor<any>>`	—	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
`style`	`CSSProperties` \| `((state: DialogTitleState) => CSSProperties` \| `undefined)`	—	Style applied to the element, or a function that returns a style object based on the component's state.

Plus the DOM props of the element it renders. Source: dialog/components/dialog-title.tsx.

Dialog.Trigger

Prop	Type	Default
`className`	`string` \| `((state: DialogTriggerState) => string` \| `undefined)`	—	CSS class applied to the element, or a function that returns a class based on the component's state.
`handle`	`DialogHandle<unknown>`	—	A handle to associate the trigger with a dialog. Can be created with the Dialog.createHandle() method.
`id`	`string`	—	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 `triggerId` prop).
`nativeButton`	`boolean`	—	Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`).
`payload`	`unknown`	—	A payload to pass to the dialog when it is opened.
`render`	`ComponentRenderFn<HTMLProps, DialogTriggerState>` \| `ReactElement<unknown, string \| JSXElementConstructor<any>>`	—	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
`style`	`CSSProperties` \| `((state: DialogTriggerState) => CSSProperties` \| `undefined)`	—	Style applied to the element, or a function that returns a style object based on the component's state.

Plus the DOM props of the element it renders. Source: dialog/components/dialog-trigger.tsx.

AlertDialog · ResponsiveDialog · Sheet · Popover