Dialog

A modal window that appears on top of the main content.

You can explore the dialog component in the following curated examples.

Anatomy

<Dialog.Root>
  <Dialog.Trigger />
  <Dialog.Backdrop />
  <Dialog.Positioner>
    <Dialog.Content>
      <Dialog.Title />
      <Dialog.Description />
      <Dialog.CloseTrigger />
    </Dialog.Content>
  </Dialog.Positioner>
</Dialog.Root>

Examples

Controlled

Manage the dialog state using the open and onOpenChange props.

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.

Alert Dialog

For critical confirmations or destructive actions, use role="alertdialog". Alert dialogs differ from regular dialogs in important ways:

• Automatic focus: The close/cancel button receives focus when opened, prioritizing the safest action
• Requires explicit dismissal: Cannot be closed by clicking outside, only via button clicks or Escape key

Lazy Mount

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

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.

Non-Modal

Use modal={false} to allow interaction with elements outside the dialog. Disables focus trapping and scroll prevention.

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.

Context

Use the Dialog.Context component to access the dialog's state and methods.

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.

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().

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 React.lazy or Next.js dynamic, wrap the imported component in Suspense:

import { Dialog } from '@ark-ui/react/dialog'
import { Suspense } from 'react'
import dynamic from 'next/dynamic'

const HeavyComponent = dynamic(() => import('./HeavyComponent'))

export const Demo = () => (
  <Dialog.Root lazyMount>
    <Dialog.Trigger>Open</Dialog.Trigger>
    <Dialog.Content>
      <Suspense fallback={<div>Loading...</div>}>
        <HeavyComponent />
      </Suspense>
    </Dialog.Content>
  </Dialog.Root>
)

API Reference

Props

Root

Backdrop

Renders a <div> element.

CloseTrigger

Renders a <button> element.

Content

Renders a <div> element.

Description

Renders a <div> element.

Positioner

Renders a <div> element.

RootProvider

Title

Renders a <h2> element.

Trigger

Renders a <button> element.

Context

API

Accessibility

Complies with the Dialog WAI-ARIA design pattern.

Keyboard Support