Dialog

A popup that opens on top of the entire page.

Preview

Installation

Install the local ghost-kit source bundle while the registry runs at localhost:3110. It contains this component and its source dependencies. Prepare the local registry first so token dependencies also resolve locally.

Install

npx shadcn@latest add http://localhost:3110/r/ghost-kit.json

Basic usage

123import { Dialog } from "@/components/ui/dialog";

<Dialog.Root><Dialog.Trigger>Open details</Dialog.Trigger><Dialog.Portal><Dialog.Popup><Dialog.Title>Details</Dialog.Title><Dialog.Close>Close</Dialog.Close></Dialog.Popup></Dialog.Portal></Dialog.Root>

Structure

Examples

State

Control the open state when another part of the page needs it.

Dialog is closed.

Open the dialog from a menu item after the menu closes.

Weekend mix

Nested dialogs

Open a second dialog for a related task.

Close confirmation

Keep an unsaved draft until the user saves or confirms a discard.

Custom focus management

Move focus to the field on open and to the chosen action on close.

Outside scroll dialog

Scroll the viewport around a tall dialog.

Inside scroll dialog

Keep scrolling inside a height-limited popup.

Elements outside the popup surface

Place the close action outside the colored surface while it stays inside the dialog's focus order.

Detached triggers

Connect a trigger to a dialog through a shared handle.

Multiple triggers

Open one dialog from two actions and show which action opened it.

API reference

For inherited behavior and additional part properties, see the Base UI Dialog API.

Dialog.Root properties
Prop	Type	Default	Description
`open`	`boolean`		Whether the dialog is currently open.
`defaultOpen`	`boolean`	`false`	Whether the dialog is initially open. To render a controlled dialog, use the `open` prop instead.
`modal`	`boolean \| "trap-focus"`	`true`	Determines if the dialog enters a modal state when open. - `true`: user interaction is limited to just the dialog: focus is trapped, document page scroll is locked, and pointer interactions on outside elements are disabled. - `false`: user interaction with the rest of the document is allowed. - `'trap-focus'`: focus is trapped inside the dialog, but document page scroll is not locked and pointer interactions outside of it remain enabled. 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: Dialog.Root.ChangeEventDetails) => 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.
`disablePointerDismissal`	`boolean`	`false`	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.
`actionsRef`	`RefObject<DialogRootActions \| null>`		A ref to imperative actions. - `unmount`: Manually unmounts the dialog. Call this after any externally controlled closing animation finishes. - `close`: Closes the dialog imperatively when called.
`handle`	`Dialog.Handle<Payload>`		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.
`children`	`ReactNode \| PayloadChildRenderFunction<Payload>`		The content of the dialog. This can be a regular React node or a render function that receives the `payload` of the active trigger.
`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).
`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.