Dialog

Import

import {
  Dialog,
  DialogTrigger,
  DialogHeading,
  DialogDescription,
  DialogCloseTrigger,
  DialogCloseIconTrigger,
} from '@cerberus-design/react'

Usage

To use the Dialog component, wrap it in a DialogProvider and use the DialogTrigger component to open the dialog. The Dialog component is a controlled component that can be used to display content in a modal.

Sizes

The Dialog component supports different sizes. You can set the size prop to xs to lg, or full.

Controlled

Manage the dialog state using the open and onOpenChange props.

Note

Notice how the dialog triggers automagically handle the state management via onOpenChange.

Root Provider

An alternative way to control the dialog is to use the RootProvider component and the useDialog hook. This way you can access the state and methods from outside the component.

Lazy Mount

Use lazyMount to render dialog content only when first opened. Combine with unmountOnExit to unmount when closed, freeing up resources.

Prefer this over conditionally rendering DialogProvider — see Conditional Rendering.

Inside Scroll

Make the content area scrollable while keeping header and footer fixed using maxHeight and overflow: auto.

Outside Scroll

Make the positioner scrollable so the dialog can extend beyond the viewport.

Initial Focus

Use initialFocusEl to control which element receives focus when the dialog opens.

Final Focus

Use finalFocusEl to control which element receives focus when the dialog closes. Defaults to the trigger element.

Context

Access the dialog's state and methods with DialogContext or the useDialogContext hook.

Open from Menu

Open a dialog imperatively from a Menu item using the onClick handler.

Nested

Nest dialogs within one another. The parent receives data-has-nested and --nested-layer-count CSS variable for styling effects like zoom-out:

[data-part='content'][data-has-nested] {
  transform: scale(calc(1 - var(--nested-layer-count) * 0.05));
}

Confirmation

Intercept close attempts to show confirmation prompts, preventing data loss from unsaved changes.

Non-Modal

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

Guides

Close Behavior

• closeOnEscape={false} - Prevent closing on Escape
• closeOnInteractOutside={false} - Prevent closing on outside click

For conditional control, use onEscapeKeyDown or onInteractOutside with e.preventDefault().

Conditional Rendering

Unmounting Dialog.Root when toggling open state can break focus, scroll lock, and cleanup. Keep the root mounted and control it with open / onOpenChange.

When you want portal content out of the DOM while closed, add lazyMount and unmountOnExit to the root.

Z-index Stacking

Use the --layer-index CSS variable for z-index management of stacked dialogs:

[data-part='content'] {
  z-index: calc(var(--layer-index));
}

Dynamic Imports

When using lazyMount with lazy or Next.js dynamic, wrap the imported component in Suspense:

Customizing

You can customize the Dialog using style props and data selectors on any slot primitve.

Primitives

You can utilize the primitive components or the css prop to customize the dialog.

API

Props

The Dialog component is an abstraction of the primitives and accepts the following props:

Root Props:

Backdrop Props:

Backdrop Data Attributes:

Backdrop CSS Variables:

CloseTrigger Props:

Content Props:

Content Data Attributes:

Content CSS Variables:

Description Props:

Positioner Props:

RootProvider Props

Title Props:

Trigger Props

Trigger Data Attributes