Dialog

A window above the page in which users read details or complete a short task.

A dialog opens a window above the page, where users read details or complete a short task without leaving the page. While it is open, focus stays in the dialog and the page behind it doesn't scroll. Users close it with the close button, the Escape key or a press outside the dialog.

Usage

dialog-default.tsx

import { Button } from "@biem/ui/components/ui/button";
import {
	Dialog,
	DialogContent,
	DialogDescription,
	DialogHeader,
	DialogTitle,
	DialogTrigger,
} from "@biem/ui/components/ui/dialog";

export function DialogDefault() {
	return (
		<Dialog>
			<DialogTrigger render={<Button variant="outline"/>}>Transfer details</DialogTrigger>
			<DialogContent>
				<DialogHeader>
					<DialogTitle>Transfer details</DialogTitle>
					<DialogDescription>
						The warehouse ships 12 cases on Monday. The store receives them on Tuesday between 6:00 and 8:00.
					</DialogDescription>
				</DialogHeader>
			</DialogContent>
		</Dialog>
	);
}

Examples

With Footer

Most tasks in a dialog end with a decision: users either complete the task or step back from it. The footer gathers the actions for that decision, and an action placed in DialogClose lets users leave the dialog without completing the task.

Footer Close Button

Where a dialog only informs, users need no decision, just a clear way back to the page. Set on the footer, showCloseButton adds a button that closes the dialog, so users return to their work as soon as they have read the content.

Without Close Button

Once the footer offers a way to cancel, a separate close button only repeats it. With showCloseButton set to false, DialogContent leaves that button out, and the decision rests with the actions of the footer. The Escape key and a press outside the dialog still close it.

Controlled

In some workflows the application decides when a dialog opens or closes, for example to close it as soon as the task that users started has finished. Through open and onOpenChange it holds the open state, so any action in the dialog can close it, and other parts of the interface can open it.

Prop	open
Type	`boolean`
Default	–
Description	Sets whether the dialog is open and makes it controlled. Update it in onOpenChange.

Prop	defaultOpen
Type	`boolean`
Default	`false`
Description	Opens the dialog at first render. The dialog then tracks its open state itself.

Prop	onOpenChange
Type	`(open: boolean, eventDetails: DialogRootChangeEventDetails) => void`
Default	–
Description	Runs when users open or close the dialog. It receives the open state that follows.

Prop	onOpenChangeComplete
Type	`(open: boolean) => void`
Default	–
Description	Runs after the dialog has opened or closed and its animations have finished.

Prop	modal
Type	`boolean \| "trap-focus"`
Default	`true`
Description	Sets how the dialog limits the rest of the page while it is open. With true, focus stays in the dialog and the page doesn't scroll. With "trap-focus", focus stays in the dialog, but the page scrolls. With false, focus can move to the rest of the page, and the page scrolls.

Prop	disablePointerDismissal
Type	`boolean`
Default	`false`
Description	Keeps the dialog open when users press outside of it. A dialog with modal set to false then also stays open when focus moves outside of it.

Prop	triggerId
Type	`string \| null`
Default	–
Description	Sets the ID of the trigger that a controlled dialog is associated with. A dialog without open doesn't need it.

Prop	defaultTriggerId
Type	`string \| null`
Default	–
Description	Sets the ID of the trigger that the dialog is associated with when defaultOpen opens it at first render.

Prop	handle
Type	`DialogHandle<Payload>`
Default	–
Description	Connects the dialog with triggers that are rendered outside of it. Create the handle with Dialog.createHandle() from @base-ui/react/dialog.

Prop	actionsRef
Type	`RefObject<DialogRootActions \| null>`
Default	–
Description	Receives the functions close and unmount. close closes the dialog from code, and unmount removes it from the DOM after a closing animation that the code controls itself.

Prop	children
Type	`ReactNode \| ((arg: { payload: Payload \| undefined }) => ReactNode)`
Default	–
Description	Holds the parts of the dialog. A function receives the payload of the trigger that opened the dialog.

DialogTrigger

Prop	handle
Type	`DialogHandle<Payload>`
Default	–
Description	Connects the trigger with a dialog that it is rendered outside of. Pass the same handle to Dialog.

Prop	payload
Type	`Payload`
Default	–
Description	Passes a value to the dialog when this trigger opens it. A function as children of Dialog receives it.

Prop	id
Type	`string`
Default	–
Description	Sets the ID of the trigger element. triggerId and defaultTriggerId of Dialog refer to it.

Prop	render
Type	`ReactElement \| render function`
Default	–
Description	Replaces the native element or composes the trigger with another component.

Prop	nativeButton
Type	`boolean`
Default	`true`
Description	Declares whether the rendered element is a native button. Set it to false when render returns a different element.

Prop	disabled
Type	`boolean`
Default	`false`
Description	Prevents users from opening the dialog with this trigger.

DialogPortal

Prop	keepMounted
Type	`boolean`
Default	`false`
Description	Keeps the portal in the DOM while the dialog is closed.

Prop	container
Type	`HTMLElement \| ShadowRoot \| RefObject<HTMLElement \| ShadowRoot \| null> \| null`
Default	–
Description	Sets the element that the portal is rendered into. Without it, the portal is appended to the body.

Prop	render
Type	`ReactElement \| render function`
Default	–
Description	Replaces the native element or composes the portal with another component.

DialogOverlay

Prop	forceRender
Type	`boolean`
Default	`false`
Description	Renders the overlay even when the dialog is nested in another dialog.

Prop	render
Type	`ReactElement \| render function`
Default	–
Description	Replaces the native element or composes the overlay with another component.

DialogContent

Prop	showCloseButton
Type	`boolean`
Default	`true`
Description	Shows the close button in the top right corner of the dialog.

Prop	initialFocus
Type	`boolean \| RefObject<HTMLElement \| null> \| ((openType: InteractionType) => boolean \| HTMLElement \| null \| void)`
Default	–
Description	Determines the element that receives focus when the dialog opens. Without it, focus moves to the first focusable element in the dialog.

Prop	finalFocus
Type	`boolean \| RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => boolean \| HTMLElement \| null \| void)`
Default	–
Description	Determines the element that receives focus when the dialog closes. Without it, focus returns to the trigger or to the element that had focus before.

Prop	render
Type	`ReactElement \| render function`
Default	–
Description	Replaces the native element or composes the content with another component.

DialogHeader

DialogHeader groups the title and the description. It renders a div and has no props of its own.

DialogTitle

Prop	render
Type	`ReactElement \| render function`
Default	–
Description	Replaces the native element or composes the title with another component.

DialogDescription

Prop	render
Type	`ReactElement \| render function`
Default	–
Description	Replaces the native element or composes the description with another component.

DialogFooter

Prop	showCloseButton
Type	`boolean`
Default	`false`
Description	Adds an outline button with the label "Close" after the children of the footer. It closes the dialog.

DialogClose

Prop	render
Type	`ReactElement \| render function`
Default	–
Description	Replaces the native element or composes the close button with another component.

Prop	nativeButton
Type	`boolean`
Default	`true`
Description	Declares whether the rendered element is a native button. Set it to false when render returns a different element.

Prop	disabled
Type	`boolean`
Default	`false`
Description	Prevents users from closing the dialog with this button.

Dialog

Usage

Examples

With Footer

Footer Close Button

Without Close Button

Controlled

Disabled Trigger

Disabled Close

API Reference

Dialog

DialogTrigger

DialogPortal

DialogOverlay

DialogContent

DialogHeader

DialogTitle

DialogDescription

DialogFooter

DialogClose

On this page

Dialog

UsageCopy Anchor Link

ExamplesCopy Anchor Link

With FooterCopy Anchor Link

Footer Close ButtonCopy Anchor Link

Without Close ButtonCopy Anchor Link

ControlledCopy Anchor Link

Disabled TriggerCopy Anchor Link

Disabled CloseCopy Anchor Link

API ReferenceCopy Anchor Link

DialogCopy Anchor Link

DialogTriggerCopy Anchor Link

DialogPortalCopy Anchor Link

DialogOverlayCopy Anchor Link

DialogContentCopy Anchor Link

DialogHeaderCopy Anchor Link

DialogTitleCopy Anchor Link

DialogDescriptionCopy Anchor Link

DialogFooterCopy Anchor Link

DialogCloseCopy Anchor Link

On this page

Usage

Examples

With Footer

Footer Close Button

Without Close Button

Controlled

Disabled Trigger

Disabled Close

API Reference

Dialog

DialogTrigger

DialogPortal

DialogOverlay

DialogContent

DialogHeader

DialogTitle

DialogDescription

DialogFooter

DialogClose