Dialog
A window on top of the page that asks the user to read or do something before going back.
Usage
import { Dialog, Portal } from '@leverui/components';
<Dialog.Root>
<Dialog.Trigger />
<Portal>
<Dialog.Backdrop />
<Dialog.Positioner>
<Dialog.Content>
<Dialog.CloseTrigger />
<Dialog.Header>
<Dialog.Title />
</Dialog.Header>
<Dialog.Body />
<Dialog.Footer />
</Dialog.Content>
</Dialog.Positioner>
</Portal>
</Dialog.Root>
Examples
Sizes
Use the size prop to change the size of the dialog component.
Cover
Use the size="cover" prop to make the dialog component cover the entire screen while revealing a small portion of the page behind.
Fullscreen
Use the size="full" prop to make the dialog component take up the entire screen.
Responsive Size
Use responsive values for the size prop to make the dialog adapt to different screen sizes.
We recommend using exact breakpoint values instead of using a base to ensure styles are properly contained.
// Might cause a style leak between the breakpoints
<Dialog.Root size={{ base: 'full', md: 'lg' }}>{/* ... */}</Dialog.Root>
// Works
<Dialog.Root size={{ mdDown: 'full', md: 'lg' }}>{/* ... */}</Dialog.Root>
Placement
Use the placement prop to change the placement of the dialog component.
Controlled
Use the open and onOpenChange prop to control the visibility of the dialog component.
Multiple Triggers
Don't mount a dialog per row. Put value on each Trigger under one Root. Read triggerValue from context to fill the title and body.
Store
An alternative way to control the dialog is to use the RootProvider component and the useDialog store hook. This way you can access the dialog state and methods from outside the dialog.
Context
Use the Dialog.Context component to access the dialog state and methods from outside the dialog.
Nested Dialogs
You can nest dialogs by using the Dialog.Root component inside another Dialog.Root component.
Open From Popover
Dialogs can be triggered from within a popover. The dialog will appear above the popover thanks to the unified z-index system.
Dialog in a popover
The button below opens a dialog. The dialog appears above this popover.
Open From Menu
Use a controlled dialog to open it from a menu item action, like a delete confirmation.
Initial Focus
Use the initialFocusEl prop to set the initial focus of the dialog component.
Without initialFocusEl, focus moves to the first element marked data-autofocus, falling back to the first tabbable element that is not marked data-no-autofocus.
<Input data-autofocus />
Inside Scroll
Use the scrollBehavior=inside prop to change the scroll behavior of the dialog when its content overflows.
Outside Scroll
Use the scrollBehavior=outside prop to change the scroll behavior of the dialog when its content overflows.
Motion Preset
Use the motionPreset prop to change the animation of the dialog component.
Alert Dialog
Set the role: "alertdialog" prop to change the dialog component to an alert dialog.
Close Button Outside
Here's an example of how to customize the Dialog.CloseTrigger component to position the close button outside the dialog component.
Non-Modal Dialog
We don't recommend using a non-modal dialog due to the accessibility concerns they present. In event you need it, here's what you can do:
- set the
modalprop tofalse - set
pointer-eventstononeon theDialog.Positionercomponent - (optional) set the
closeOnInteractOutsideprop tofalse
DataList
Here's an example of how to compose the dialog component with the DataList component.
Guides
Accessibility and focus
Screen readers use the title as the dialog's name and the description as its
explanation. Focus moves in on open and returns on close. Put the content in a
Portal so a parent cannot clip it. Theme variables on only part of the page?
See portal and theme scoping.
Action triggers
Dialog.ActionTrigger is a button that does something, then closes the dialog.
No default styles. Style it with class, style, or
.leverui-dialog__actionTrigger.
Shared defaults
Dialog.PropsProvider sets default style and mount props for the dialogs
inside it. A prop on a dialog wins. size can be responsive.
Props
Root
| Prop | Default | Type | Description |
|---|---|---|---|
closeOnEscape | true | boolean | Close on Escape. |
closeOnInteractOutside | true | boolean | Close on a click outside. |
lazyMount | true | boolean | Wait for the first open to render content. |
modal | true | boolean | Block clicks and taps outside; hide content below. |
preventScroll | true | boolean | Stop the page behind from scrolling while open. |
role | 'dialog' | 'dialog' | 'alertdialog' | ARIA role. |
trapFocus | true | boolean | Keep keyboard focus inside while open. |
unmountOnExit | true | boolean | Remove content from the page on close. |
placement | 'top' | 'center' | 'top' | 'bottom' | Position on the screen. |
scrollBehavior | 'outside' | 'inside' | 'outside' | Scroll long content inside the dialog, or the whole dialog. |
size | 'md' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'cover' | 'full' | Dialog size. |
motionPreset | 'scale' | 'scale' | 'slide-in-bottom' | 'slide-in-top' | 'slide-in-left' | 'slide-in-right' | 'none' | Open and close animation. |
unstyled | — | boolean | Turn off the Lever UI styles. |
aria-label | — | string | Screen reader label. Use when there is no title. |
defaultOpen | false | boolean | Open on first render. |
defaultTriggerValue | — | string | Active trigger value on first render. |
finalFocusEl | — | () => MaybeElement | Element focused on close. |
id | — | string | Unique id. |
ids | — | Element ID map | Your own ids for the dialog's elements. |
immediate | — | boolean | Apply present changes right away, not next frame. |
initialFocusEl | — | () => MaybeElement | Element focused on open. |
onEscapeKeyDown | — | (event: KeyboardEvent) => void | Called when Escape is pressed. |
onExitComplete | — | VoidFunction | Called when the closing animation ends. |
onFocusOutside | — | (event: FocusOutsideEvent) => void | Called when focus moves outside. |
onInteractOutside | — | (event: InteractOutsideEvent) => void | Called on an interaction outside. |
onOpenChange | — | (details: OpenChangeDetails) => void | Called when the dialog opens or closes. |
onPointerDownOutside | — | (event: PointerDownOutsideEvent) => void | Called on pointer down outside. |
onRequestDismiss | — | (event: LayerDismissEvent) => void | Called when closed because a parent layer closed. |
onTriggerValueChange | — | (details: TriggerValueChangeDetails) => void | Called when the active trigger changes. |
open | — | boolean | Open state, when you control it. |
persistentElements | — | (() => Element | null)[] | Getters for outside elements that stay clickable and do not close it. |
present | — | boolean | Presence, when you control it. |
restoreFocus | — | boolean | Return focus to the element that had it before. |
skipAnimationOnMount | false | boolean | Skip the opening animation when starting open. |
triggerValue | — | string | Active trigger value, when you control it. |
Trigger
| Prop | Default | Type | Description |
|---|---|---|---|
as | button | Native tag name | HTML tag to render. |
asChild | — | Solid render function | Render your own element with the trigger's props. |
value | — | string | Value that identifies this trigger. |
Customize with CSS
Load the package stylesheet first, then your CSS. Each
part has a stable class, such as .leverui-dialog__content or
.leverui-dialog__header, and takes class and style. unstyled turns off
the default styles and keeps the part classes.
<Dialog.Content class="profile-dialog">...</Dialog.Content>
.profile-dialog {
--leverui-colors-bg-panel: #18242b;
border: 1px solid #5b8a96;
}