Dialog

Overview

Dialog is a modal component that displays content in a centered overlay with a backdrop. It supports nested dialogs with automatic scaling animations, focus trapping, and keyboard controls.

Basic usage

import { Dialog } from '@raystack/apsara';

<Dialog>
  <Dialog.Trigger asChild>
    <button>Open dialog</button>
  </Dialog.Trigger>
  
  <Dialog.Content>
    <Dialog.Header>
      <Dialog.Title>Dialog title</Dialog.Title>
    </Dialog.Header>
    
    <Dialog.Body>
      <Dialog.Description>
        This is the dialog content.
      </Dialog.Description>
    </Dialog.Body>
    
    <Dialog.Footer>
      <Dialog.Close asChild>
        <button>Cancel</button>
      </Dialog.Close>
      <button>Confirm</button>
    </Dialog.Footer>
  </Dialog.Content>
</Dialog>

Components

Dialog (Root)

The root component that manages dialog state and context. Based on @base-ui/react Dialog.Root.

boolean

Controls the open state of the dialog (controlled mode).

boolean

The initial open state in uncontrolled mode.

(open: boolean) => void

Callback fired when the open state changes.

Whether the dialog is modal (blocks interaction with content behind it).

Dialog.Trigger

A button that opens the dialog when clicked.

boolean

When true, merges props with the immediate child element instead of rendering a button.

Dialog.Content

The content container rendered in a portal with backdrop and viewport.

boolean

default:"true"

Whether to show the close button in the top-right corner.

object

Props for the backdrop overlay, including a blur property to enable backdrop blur.

string | number

Custom width for the dialog content.

boolean

default:"true"

Toggles nested dialog animation (scaling and translation) when dialogs are stacked.

string

Additional CSS classes for the dialog popup.

Dialog.Header

A flex container for the dialog header, typically containing the title and description.

Dialog.Title

The accessible title element for the dialog. Required for accessibility.

Dialog.Description

An optional description element that provides additional context about the dialog.

Dialog.Body

A flex column container for the main dialog content.

Dialog.Footer

A flex container aligned to the right for action buttons.

Dialog.Close

A button that closes the dialog when clicked.

boolean

When true, merges props with the immediate child element instead of rendering a button.

Dialog.CloseButton

A styled close button with an X icon, automatically positioned in the top-right corner.

Usage examples

Custom width dialog

<Dialog>
  <Dialog.Trigger asChild>
    <button>Open wide dialog</button>
  </Dialog.Trigger>
  
  <Dialog.Content width={800}>
    <Dialog.Header>
      <Dialog.Title>Wide dialog</Dialog.Title>
    </Dialog.Header>
    <Dialog.Body>
      Content with custom width.
    </Dialog.Body>
  </Dialog.Content>
</Dialog>

Dialog with blurred backdrop

<Dialog>
  <Dialog.Trigger asChild>
    <button>Open dialog</button>
  </Dialog.Trigger>
  
  <Dialog.Content overlay={{ blur: true }}>
    <Dialog.Header>
      <Dialog.Title>Blurred background</Dialog.Title>
    </Dialog.Header>
    <Dialog.Body>
      The backdrop behind this dialog is blurred.
    </Dialog.Body>
  </Dialog.Content>
</Dialog>

Nested dialogs

<Dialog>
  <Dialog.Trigger asChild>
    <button>Open first dialog</button>
  </Dialog.Trigger>
  
  <Dialog.Content>
    <Dialog.Header>
      <Dialog.Title>First dialog</Dialog.Title>
    </Dialog.Header>
    <Dialog.Body>
      <Dialog>
        <Dialog.Trigger asChild>
          <button>Open second dialog</button>
        </Dialog.Trigger>
        <Dialog.Content>
          <Dialog.Header>
            <Dialog.Title>Second dialog</Dialog.Title>
          </Dialog.Header>
          <Dialog.Body>
            Nested dialog with automatic scaling animation.
          </Dialog.Body>
        </Dialog.Content>
      </Dialog>
    </Dialog.Body>
  </Dialog.Content>
</Dialog>

Controlled dialog

function ControlledDialog() {
  const [open, setOpen] = useState(false);
  
  return (
    <Dialog open={open} onOpenChange={setOpen}>
      <Dialog.Trigger asChild>
        <button>Open dialog</button>
      </Dialog.Trigger>
      
      <Dialog.Content>
        <Dialog.Header>
          <Dialog.Title>Controlled dialog</Dialog.Title>
        </Dialog.Header>
        <Dialog.Body>
          This dialog's state is controlled externally.
        </Dialog.Body>
        <Dialog.Footer>
          <button onClick={() => setOpen(false)}>Close</button>
        </Dialog.Footer>
      </Dialog.Content>
    </Dialog>
  );
}

Without close button

<Dialog>
  <Dialog.Trigger asChild>
    <button>Open dialog</button>
  </Dialog.Trigger>
  
  <Dialog.Content showCloseButton={false}>
    <Dialog.Header>
      <Dialog.Title>No close button</Dialog.Title>
    </Dialog.Header>
    <Dialog.Body>
      Use the footer buttons to close.
    </Dialog.Body>
    <Dialog.Footer>
      <Dialog.Close asChild>
        <button>Close</button>
      </Dialog.Close>
    </Dialog.Footer>
  </Dialog.Content>
</Dialog>

Accessibility features

Focus trap: Focus is trapped within the dialog when open
ESC to close: Press Escape to close the dialog
Focus return: Focus returns to the trigger element when closed
ARIA labels: Proper ARIA attributes for screen readers
Close button: Includes accessible aria-label="Close dialog"
Modal behavior: Blocks interaction with content behind the dialog

Trigger patterns

The Dialog.Trigger component can be used in two ways:

Default button: Renders a button element when no children are provided or asChild is false
Custom trigger: Use asChild prop to merge dialog trigger functionality with your own button component

{/* Default button */}
<Dialog.Trigger>Open</Dialog.Trigger>

{/* Custom trigger */}
<Dialog.Trigger asChild>
  <button className="custom-button">Open</button>
</Dialog.Trigger>

Get Started

Guides

Layout Components

Navigation Components

Data Display

Form Components

Feedback Components

Overlay Components

Utility Components

Overview

Basic usage

Components

Dialog (Root)

Dialog.Trigger

Dialog.Content

Dialog.Header

Dialog.Title

Dialog.Description

Dialog.Body

Dialog.Footer

Dialog.Close

Dialog.CloseButton

Usage examples

Custom width dialog

Dialog with blurred backdrop

Nested dialogs

Controlled dialog

Without close button

Accessibility features

Trigger patterns

​Overview

​Basic usage

​Components

​Dialog (Root)

​Dialog.Trigger

​Dialog.Content

​Dialog.Header

​Dialog.Title

​Dialog.Description

​Dialog.Body

​Dialog.Footer

​Dialog.Close

​Dialog.CloseButton

​Usage examples

​Custom width dialog

​Dialog with blurred backdrop

​Nested dialogs

​Controlled dialog

​Without close button

​Accessibility features

​Trigger patterns

Overview

Basic usage

Components

Dialog (Root)

Dialog.Trigger

Dialog.Content

Dialog.Header

Dialog.Title

Dialog.Description

Dialog.Body

Dialog.Footer

Dialog.Close

Dialog.CloseButton

Usage examples

Custom width dialog

Dialog with blurred backdrop

Nested dialogs

Controlled dialog

Without close button

Accessibility features

Trigger patterns