Dialog

A window on top of the page that asks the user to read or do something before going back.

Usage

Code
import { Dialog, Portal } from '@leverui/components';
Code
<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.

Code
// 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.

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.

Code
<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 modal prop to false
  • set pointer-events to none on the Dialog.Positioner component
  • (optional) set the closeOnInteractOutside prop to false

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

PropDefaultTypeDescription
closeOnEscapetruebooleanClose on Escape.
closeOnInteractOutsidetruebooleanClose on a click outside.
lazyMounttruebooleanWait for the first open to render content.
modaltruebooleanBlock clicks and taps outside; hide content below.
preventScrolltruebooleanStop the page behind from scrolling while open.
role'dialog''dialog' | 'alertdialog'ARIA role.
trapFocustruebooleanKeep keyboard focus inside while open.
unmountOnExittruebooleanRemove 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—booleanTurn off the Lever UI styles.
aria-label—stringScreen reader label. Use when there is no title.
defaultOpenfalsebooleanOpen on first render.
defaultTriggerValue—stringActive trigger value on first render.
finalFocusEl—() => MaybeElementElement focused on close.
id—stringUnique id.
ids—Element ID mapYour own ids for the dialog's elements.
immediate—booleanApply present changes right away, not next frame.
initialFocusEl—() => MaybeElementElement focused on open.
onEscapeKeyDown—(event: KeyboardEvent) => voidCalled when Escape is pressed.
onExitComplete—VoidFunctionCalled when the closing animation ends.
onFocusOutside—(event: FocusOutsideEvent) => voidCalled when focus moves outside.
onInteractOutside—(event: InteractOutsideEvent) => voidCalled on an interaction outside.
onOpenChange—(details: OpenChangeDetails) => voidCalled when the dialog opens or closes.
onPointerDownOutside—(event: PointerDownOutsideEvent) => voidCalled on pointer down outside.
onRequestDismiss—(event: LayerDismissEvent) => voidCalled when closed because a parent layer closed.
onTriggerValueChange—(details: TriggerValueChangeDetails) => voidCalled when the active trigger changes.
open—booleanOpen state, when you control it.
persistentElements—(() => Element | null)[]Getters for outside elements that stay clickable and do not close it.
present—booleanPresence, when you control it.
restoreFocus—booleanReturn focus to the element that had it before.
skipAnimationOnMountfalsebooleanSkip the opening animation when starting open.
triggerValue—stringActive trigger value, when you control it.

Trigger

PropDefaultTypeDescription
asbuttonNative tag nameHTML tag to render.
asChild—Solid render functionRender your own element with the trigger's props.
value—stringValue 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.

Code
<Dialog.Content class="profile-dialog">...</Dialog.Content>
Code
.profile-dialog {
  --leverui-colors-bg-panel: #18242b;
  border: 1px solid #5b8a96;
}