Dialog

The React Dialog component shows a modal window on top of the page to display content or collect user input. It is used for things like forms, messages, or actions that need user attention.

It opens as an overlay and can block or allow interaction with the background. For example, you can use it to edit a profile, show details, or ask users to take an action.

Built with React and react-aria-components Components, and styled using Tailwind CSS. It supports keyboard navigation, focus management, and accessible modal behavior.

Installation

npx @tailgrids/cli add dialog

Anatomy

Import the component parts and combine them according to your requirements.

import {
  Dialog,
  DialogTrigger,
  DialogOverlay,
  DialogContent,
  DialogHeader,
  DialogTitle,
  DialogDescription,
  DialogBody,
  DialogFooter,
  DialogClose
} from "@/registry/core/dialog";

export default function DialogAnatomy() {
  return (
    <Dialog>
      <DialogTrigger />
      <DialogOverlay>
        <DialogContent>
          <DialogHeader>
            <DialogTitle />
            <DialogDescription />
          </DialogHeader>
          <DialogBody />
          <DialogFooter>
            <DialogClose />
          </DialogFooter>
        </DialogContent>
      </DialogOverlay>
    </Dialog>
  );
}

Usage

Import the dialog components and compose them to build your modal.

import {
  Dialog,
  DialogTrigger,
  DialogOverlay,
  DialogContent,
  DialogHeader,
  DialogTitle,
  DialogDescription,
  DialogFooter,
  DialogClose
} from "@/registry/core/dialog";

export default function DialogExample() {
  return (
    <Dialog>
      <DialogTrigger>Open Dialog</DialogTrigger>
      <DialogOverlay isDismissable>
        <DialogContent>
          <DialogHeader>
            <DialogTitle>Dialog Title</DialogTitle>
            <DialogDescription>
              A short description of the dialog purpose.
            </DialogDescription>
          </DialogHeader>
          <DialogFooter>
            <DialogClose>Cancel</DialogClose>
          </DialogFooter>
        </DialogContent>
      </DialogOverlay>
    </Dialog>
  );
}

Examples

Controlled Dialog

Show Information

Display read-only information such as release notes, announcements, or details that the user needs to acknowledge.

Ask a Question

Use a confirmation dialog to ask the user a yes/no question before performing a destructive or irreversible action.

Collect Input

Present a form inside the dialog to collect user input such as profile settings, preferences, or text fields.

Multiple Actions

Offer the user multiple choices or actions to select from within a single dialog.

Without Close Button

You can remove the default close button at the top using showCloseButton={false} on DialogContent.

Sticky Footer

Keep the footer actions visible while the dialog content scrolls. Useful for long content like terms of service or license agreements.

Without Overlay

Render the dialog without a backdrop overlay by using DialogContent directly without wrapping it in DialogOverlay. This is useful for non-blocking notifications or confirmation screens where the background should remain visible.

API Reference

Dialog

The root component that manages the open/close state of the dialog.

DialogTrigger

The button element that opens the dialog when pressed.

DialogOverlay

The backdrop overlay that covers the page behind the dialog. Wraps DialogContent and controls dismiss behavior.

DialogContent

The main dialog panel. Composes Modal and Dialog from react-aria-components. Must be placed inside a DialogOverlay.

DialogHeader

A semantic container for the title and description at the top of the dialog.

DialogTitle

The dialog title. Uses react-aria's Heading with slot="title" for proper ARIA labelling.

DialogDescription

A paragraph for supplementary text that describes the dialog's purpose.

DialogBody

A scrollable content area between the header and footer.

DialogFooter

An action bar at the bottom of the dialog for buttons and actions.

DialogClose

A button with slot="close" that automatically closes the nearest dialog when pressed. Can wrap any content for custom close triggers.

Accessibility

• Focus management: The dialog keeps focus while open and returns focus to the trigger when it closes.
• Keyboard support: Users can press the Escape key to close the dialog. You can turn off this behavior if needed.
• Trigger behavior: Users can open and close the dialog using a trigger or a close button with a mouse or keyboard.
• Screen reader support: Screen readers announce the dialog as a modal, and background content stays hidden while it is open.
• ARIA labeling: Use DialogTitle and DialogDescription to describe the dialog content clearly.
• Outside click: Users can close the dialog by clicking outside when isDismissable is enabled.