Skip to contents

Dialog

A popup that opens on top of the entire page.

View as Markdown View source

Usage guidelines

  • Dialog doesn't support gestures: Use Drawer when you need gesture support or snap points. A panel that slides in from the edge of the screen and doesn't need gesture support is a positioned Dialog.

Anatomy

Import the component and assemble its parts:

Examples

State

By default, Dialog is an uncontrolled component that manages its own state.

Use bind:open if you need to access or control the state of the dialog. For example, you can control the dialog state in order to open it imperatively from another place in your app.

It's also common to use onOpenChange if your app needs to do something when the dialog is closed or opened. This is recommended over $effect when reacting to state changes. The callback runs before the state changes, and the binding sets the new state, so there is no setter to call.

Open from a menu

In order to open a dialog using a menu, control the dialog state and open it imperatively using the onclick handler on the menu item. Bind open on <Dialog.Root> and set it from that handler.

Nested dialogs

You can nest dialogs within one another normally.

Use the [data-nested-dialog-open] selector and the var(--nested-dialogs) CSS variable to customize the styling of the parent dialog. Backdrops of the child dialogs won't be rendered so that you can present the parent dialog in a clean way behind the one on top of it.

Close confirmation

This example shows a nested confirmation dialog that opens if the text entered in the parent dialog is going to be discarded.

To implement this, both dialogs should be controlled. The confirmation dialog may be opened when onOpenChange callback of the parent dialog receives a request to close. This way, the confirmation is automatically shown when the user clicks the backdrop, presses the Esc key, or clicks a close button. Call eventDetails.cancel() in that callback to keep the parent dialog open while the confirmation shows.

Custom focus management

You can control where the focus goes when the dialog opens and closes using the initialFocus and finalFocus props on the <Dialog.Popup> component.

You can also set these props to false to prevent focus from moving when the dialog opens or closes, or to a function that returns the element to focus based on the interaction type. There is no ref object: pass an element, or a function that returns the element.

Outside scroll dialog

The dialog can be made scrollable by using <Dialog.Viewport> as an outer scrollable container for <Dialog.Popup> while the popup can extend past the bottom edge. The scrollable area uses the Scroll Area component to provide custom scrollbars.

Inside scroll dialog

The dialog can be made scrollable by making an inner container scrollable while the popup stays fully on screen. <Dialog.Viewport> is used as a positioning container for <Dialog.Popup>, while an inner scrollable area is created using the Scroll Area component.

Placing elements outside the popup

When adding elements that should appear "outside" the colored popup area, continue to place them inside <Dialog.Popup>, but create a child element that has the popup styles. This ensures they are kept in the tab order and announced correctly by screen readers.

<Dialog.Popup> has pointer-events: none, while inner content (the colored popup and close button) has pointer-events: auto so clicks on the backdrop continue to be registered.

Detached triggers

A dialog can be controlled by a trigger located either inside or outside the <Dialog.Root> component. For simple, one-off interactions, place the <Dialog.Trigger> inside <Dialog.Root>, as shown in the example at the top of this page.

However, if defining the dialog's content next to its trigger is not practical, you can use a detached trigger. This involves placing the <Dialog.Trigger> outside of <Dialog.Root> and linking them with a handle created by the Dialog.createHandle() function.

The imperative methods on the handle, such as open() and openWithPayload(), require a <Dialog.Root> using the same handle to be mounted. Calls made while no root is attached to the handle — before one mounts, or after it unmounts — are ignored. Each time a root mounts, it starts from fresh state: a call made while no root was attached is not replayed, and no open state carries over from a previous mount.

Multiple triggers

A single dialog can be opened by multiple trigger elements. You can achieve this by using the same handle for several detached triggers, or by placing multiple <Dialog.Trigger> components inside a single <Dialog.Root>.

The dialog can render different content depending on which trigger opened it. This is achieved by passing a payload to the <Dialog.Trigger> and reading it from the children snippet of <Dialog.Root>, which receives { payload }.

The payload can be strongly typed by providing a type argument to the createHandle() function:

Controlled mode with multiple triggers

You can control the dialog's open state externally using the open and onOpenChange props on <Dialog.Root>. This allows you to manage the dialog's visibility based on your application's state. When using multiple triggers, you have to manage which trigger is active with the triggerId prop on <Dialog.Root> and the id prop on each <Dialog.Trigger>.

Note that there is no separate onTriggerIdChange prop. Instead, the onOpenChange callback receives an additional argument, eventDetails, which contains the trigger element that initiated the state change.

API reference

Root

Groups all parts of the dialog. Doesn't render its own HTML element.

open boolean false
Name
open
Description

Whether the dialog is open. Use bind:open to share it with the parent. A value passed without bind: holds until the parent changes it.

Type
boolean
Default
false
Binding
bind:open
modal boolean | 'trap-focus' true
Name
modal
Description

true traps focus, locks page scroll, and blocks outside pointer interaction. false leaves the rest of the page usable. 'trap-focus' traps focus without locking scroll or outside pointers.

Type
boolean | 'trap-focus'
Default
true
onOpenChange function —
Name
onOpenChange
Description

Called before the open state changes. Call eventDetails.cancel() to veto it.

Type
(open: boolean, eventDetails: DialogChangeEventDetails) => void
onOpenChangeComplete function —
Name
onOpenChangeComplete
Description

Called after the open or close animation finishes.

Type
(open: boolean) => void
disablePointerDismissal boolean false
Name
disablePointerDismissal
Description

Do not close on outside presses. Non-modal dialogs also stay open when focus moves outside.

Type
boolean
Default
false
handle DialogHandle<Payload> —
Name
handle
Description

Connects detached triggers. Create one with Dialog.createHandle().

Type
DialogHandle<Payload>
triggerId string | null null
Name
triggerId
Description

Id of the trigger that owns the dialog. Use bind:triggerId to share it with the parent. Pass it with an initial open to name the trigger the dialog starts from. An id written by a trigger press resets to null once the popup unmounts.

Type
string | null
Default
null
Binding
bind:triggerId
children Snippet<[{ payload: Payload | undefined }]> —
Name
children
Type
Snippet<[{ payload: Payload | undefined }]>

Trigger

A button that opens the dialog. Renders a <button> element.

handle DialogHandle<Payload> —
Name
handle
Description

Associates this trigger with a dialog that is not its parent.

Type
DialogHandle<Payload>
payload Payload —
Name
payload
Description

Passed to the dialog when this trigger opens it.

Type
Payload
id string | null —
Name
id
Type
string | null
nativeButton boolean true
Name
nativeButton
Description

false renders through render instead of a native button.

Type
boolean
Default
true
render Snippet<[props: DialogTriggerHostProps, state: DialogTriggerState, children: Snippet | undefined]> —
Name
render
Type
Snippet<[props: DialogTriggerHostProps, state: DialogTriggerState, children: Snippet | undefined]>
disabled boolean
Name
disabled
Description

Whether the trigger is currently disabled.

Type
boolean
open boolean
Name
open
Description

Whether the dialog is open and was opened by this trigger.

Type
boolean
data-popup-open
Present when the corresponding dialog is open.
data-disabled
Present when the trigger is disabled.

Portal

A portal element that moves the popup to a different part of the DOM. Renders through the shared FloatingPortal, which appends to <body> by default.

keepMounted boolean false
Name
keepMounted
Description

Keep the portal mounted while the popup is closed.

Type
boolean
Default
false
container HTMLElement | ShadowRoot | null —
Name
container
Description

Element the portal is appended to. undefined uses the parent portal or document.body. null waits and does not mount until an element or shadow root is set. There is no ref object.

Type
HTMLElement | ShadowRoot | null
render Snippet<[props: HTMLAttributes<HTMLDivElement> & Record<symbol, Attachment<HTMLDivElement>>, state: DialogPortalState, children: Snippet | undefined]> —
Name
render
Description

Replace the portal element. The snippet receives host props, an empty state, and the children snippet.

Type
Snippet<[props: HTMLAttributes<HTMLDivElement> & Record<symbol, Attachment<HTMLDivElement>>, state: DialogPortalState, children: Snippet | undefined]>

Backdrop

An overlay displayed beneath the popup. Renders a <div> element.

forceRender boolean false
Name
forceRender
Description

Render the backdrop even when this dialog is nested.

Type
boolean
Default
false
render Snippet<[props: HTMLAttributes<HTMLDivElement> & Record<symbol, Attachment<HTMLDivElement>>, state: DialogBackdropState, children: Snippet | undefined]> —
Name
render
Type
Snippet<[props: HTMLAttributes<HTMLDivElement> & Record<symbol, Attachment<HTMLDivElement>>, state: DialogBackdropState, children: Snippet | undefined]>
open boolean
Name
open
Type
boolean
transitionStatus 'starting' | 'ending' | 'idle' | undefined
Name
transitionStatus
Type
'starting' | 'ending' | 'idle' | undefined
data-open
Present when the dialog is open.
data-closed
Present when the dialog is closed.
data-starting-style
Present when the dialog begins animating in.
data-ending-style
Present when the dialog is animating out.

Viewport

A positioning container for the dialog popup. Renders a <div> element.

render Snippet<[props: HTMLAttributes<HTMLDivElement> & Record<symbol, Attachment<HTMLDivElement>>, state: DialogViewportState, children: Snippet | undefined]> —
Name
render
Type
Snippet<[props: HTMLAttributes<HTMLDivElement> & Record<symbol, Attachment<HTMLDivElement>>, state: DialogViewportState, children: Snippet | undefined]>
open boolean
Name
open
Description

Whether the dialog is currently open.

Type
boolean
transitionStatus 'starting' | 'ending' | 'idle' | undefined
Name
transitionStatus
Description

Open/close motion phase.

Type
'starting' | 'ending' | 'idle' | undefined
nested boolean
Name
nested
Description

Whether this dialog is nested inside a parent dialog.

Type
boolean
nestedDialogOpen boolean
Name
nestedDialogOpen
Description

Whether a dialog nested inside this one is open.

Type
boolean
data-open
Present when the dialog is open.
data-closed
Present when the dialog is closed.
data-nested
Present when the dialog is nested within another dialog.
data-nested-dialog-open
Present when the dialog has other open dialogs nested within it.
data-starting-style
Present when the dialog begins animating in.
data-ending-style
Present when the dialog is animating out.

A container for the dialog contents. Renders a <div> element.

initialFocus DialogFocusTarget —
Name
initialFocus
Description

Element to focus when the dialog opens. Touch opens focus the popup itself unless this says otherwise. Pass an element or a function. There is no ref object.

Type
DialogFocusTarget
finalFocus DialogFocusTarget —
Name
finalFocus
Description

Element to focus when the dialog closes. Pass an element or a function. There is no ref object.

Type
DialogFocusTarget
render Snippet<[props: HTMLAttributes<HTMLDivElement> & Record<symbol, Attachment<HTMLDivElement>>, state: DialogPopupState, children: Snippet | undefined]> —
Name
render
Type
Snippet<[props: HTMLAttributes<HTMLDivElement> & Record<symbol, Attachment<HTMLDivElement>>, state: DialogPopupState, children: Snippet | undefined]>
open boolean
Name
open
Description

Whether the dialog is currently open.

Type
boolean
transitionStatus 'starting' | 'ending' | 'idle' | undefined
Name
transitionStatus
Description

Open/close motion phase.

Type
'starting' | 'ending' | 'idle' | undefined
nested boolean
Name
nested
Description

Whether this dialog is nested inside a parent dialog.

Type
boolean
nestedDialogOpen boolean
Name
nestedDialogOpen
Description

Whether a dialog nested inside this one is open.

Type
boolean
data-open
Present when the dialog is open.
data-closed
Present when the dialog is closed.
data-nested
Present when the dialog is nested within another dialog.
data-nested-dialog-open
Present when the dialog has other open dialogs nested within it.
data-starting-style
Present when the dialog begins animating in.
data-ending-style
Present when the dialog is animating out.
--nested-dialogs
Indicates how many dialogs are nested within.

Title

A heading that labels the dialog. Renders an <h2> element.

render Snippet<[props: HTMLAttributes<HTMLHeadingElement> & Record<symbol, Attachment<HTMLHeadingElement>>, state: DialogTitleState, children: Snippet | undefined]> —
Name
render
Type
Snippet<[props: HTMLAttributes<HTMLHeadingElement> & Record<symbol, Attachment<HTMLHeadingElement>>, state: DialogTitleState, children: Snippet | undefined]>

Description

A paragraph with additional information about the dialog. Renders a <p> element.

render Snippet<[props: HTMLAttributes<HTMLParagraphElement> & Record<symbol, Attachment<HTMLParagraphElement>>, state: DialogDescriptionState, children: Snippet | undefined]> —
Name
render
Type
Snippet<[props: HTMLAttributes<HTMLParagraphElement> & Record<symbol, Attachment<HTMLParagraphElement>>, state: DialogDescriptionState, children: Snippet | undefined]>

Close

A button that closes the dialog. Renders a <button> element.

nativeButton boolean true
Name
nativeButton
Description

false renders through render instead of a native button.

Type
boolean
Default
true
render Snippet<[props: DialogTriggerHostProps, state: DialogCloseState, children: Snippet | undefined]> —
Name
render
Type
Snippet<[props: DialogTriggerHostProps, state: DialogCloseState, children: Snippet | undefined]>
disabled boolean
Name
disabled
Type
boolean
data-disabled
Present when the button is disabled.

createHandle

Creates a new handle to connect a Dialog.Root with detached Dialog.Trigger components. Pass a type argument to type the payload, as in Dialog.createHandle<number>(). It returns a Dialog.Handle<Payload>. The library also exports it by name as createDialogHandle.

Handle

Controls a Dialog imperatively and associates detached Dialog.Trigger components with a Dialog.Root. Create one with Dialog.createHandle() and pass it to the handle prop of the root and of any triggers rendered outside of it.

The imperative methods take effect only while a root using this handle is mounted; calls made before a root attaches (or after it unmounts) are ignored.

MemberDescription
isOpenWhether the dialog is currently open. Read-only. false while no root is attached to the handle.
payloadThe payload of the trigger that opened the dialog, or undefined. Read-only.
open(triggerId)Opens the dialog, optionally associating it with a trigger. Call it in an event handler or an effect, not during rendering.
openWithPayload(payload)Opens the dialog with the given payload, without associating it with any trigger.
close()Closes the dialog.
unmount()Removes the popup at once, without waiting for the exit animation.