Dialog

React Dialog components display a modal overlay above the main page content. They are commonly used to show information, ask a question, collect input from forms, or offer multiple actions that require the user's attention before continuing.

This Dialog component is built with React and styled using Tailwind CSS. It uses react-aria-components for accessibility, focus management, and keyboard interactions out of the box.

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: Focus is automatically trapped inside the dialog when open and restored to the trigger on close.
• Keyboard Support: Press Escape to close the dialog (configurable via isKeyboardDismissDisabled on DialogOverlay).
• ARIA Labelling: DialogTitle uses slot="title" to automatically set aria-labelledby on the dialog.
• Screen Readers: The dialog is announced as a modal overlay, and background content is hidden from assistive technology.
• Dismiss on Outside Click: Clicking the overlay backdrop closes the dialog when isDismissable is true on DialogOverlay.
• Semantic HTML: Uses native dialog semantics via react-aria-components for maximum compatibility.