Dialog

Purpose and Scope

Dialog documents the ARIA based shadcn/ui component used when an interface needs a temporary window layered over the current page. The source page describes it as a window over the primary window, or over another dialog window, while rendering the content underneath inert. That framing matters because the component is not just a styled card; it is a modal interaction pattern that should guide focus, isolate the active task, and make background content unavailable while the dialog is open. Sources: apps/v4/content/docs/components/aria/dialog.mdx

The shadcn/ui documentation presents Dialog as a first-party component page with a preview, installation choices, usage imports, composition guidance, examples, RTL coverage, and an API pointer to React Aria Modal. The component is marked as base aria, which means the reader should understand it as part of the ARIA component family rather than the Radix or base-only catalog. It is suitable for editing profile details, confirming contextual changes, or collecting a short form without navigating away from the current screen. Sources: apps/v4/content/docs/components/aria/dialog.mdx

Relevant Source Files

apps/v4/content/docs/components/aria/dialog.mdx — Primary Dialog documentation, including frontmatter metadata, install commands, manual dependency notes, usage imports, composition tree, close button examples, sticky footer, scrollable content, RTL preview, and API reference pointer.
apps/v4/content/docs/components/aria/alert-dialog.mdx — Neighboring ARIA modal component documentation used to distinguish regular dialogs from interruptive alert dialogs and to show the shared React Aria Modal API family.
apps/v4/content/docs/changelog/2024-08-npx-shadcn-init.mdx — CLI rewrite notes that explain why component installation is driven by npx shadcn add, framework detection, remote registry support, error handling, and monorepo support.
apps/v4/content/docs/changelog/2025-04-shadcn-2-5.mdx — Resolve anywhere notes that explain how registry installation can place files in flexible locations and resolve imports and aliases across an app.
apps/v4/content/docs/changelog/2025-12-shadcn-create.mdx — Preset and visual style notes that explain why component code can be transformed for selected libraries, icons, spacing, structure, fonts, and visual styles such as Nova.
apps/v4/content/docs/changelog/2026-04-shadcn-apply.mdx — Apply command notes that describe switching presets in existing projects while reinstalling components and preserving current base and RTL settings.

Installation Flow

The fastest supported path is the CLI command shown on the Dialog page. Running the add command installs the registry item for the dialog component into the local project, so the project owns the resulting source file and can edit it directly. That local-code model is consistent with the larger CLI rewrite, where the add command can install components, themes, hooks, utilities, and remote registry content. For Dialog, the documented command is intentionally narrow: add the named component, then import it from the configured user interface component alias. Sources: apps/v4/content/docs/components/aria/dialog.mdx, apps/v4/content/docs/changelog/2024-08-npx-shadcn-init.mdx

npx shadcn@latest add dialog

Manual installation is documented for projects that do not want the registry command or need to copy component source explicitly. The manual path requires installing react aria components, copying the Dialog source into the project as the local user interface component file, and updating import paths to match the project setup. This reinforces an important shadcn/ui convention: the installed component is application code, not an opaque package import. After copying, teams can adjust layout, class names, close controls, motion, and project aliases while preserving the accessible behavior supplied by the ARIA foundation. Sources: apps/v4/content/docs/components/aria/dialog.mdx

npm install react-aria-components

Core Primitives and Composition

The public primitives shown by the usage example are DialogTrigger, Dialog, DialogHeader, DialogTitle, and DialogDescription, commonly paired with Button from the local button component. DialogTrigger owns the relationship between the trigger control and the overlay content. Dialog is the overlaid window itself. DialogHeader groups introductory content, while DialogTitle and DialogDescription provide the accessible name and supporting explanation users need before acting. DialogFooter appears in the composition tree as the conventional place for actions, even though the minimal usage example focuses only on the header content. Sources: apps/v4/content/docs/components/aria/dialog.mdx

import { Button } from "@/components/ui/button"
import {
  Dialog,
  DialogDescription,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog"

<DialogTrigger>
  <Button>Open</Button>
  <Dialog>
    <DialogHeader>
      <DialogTitle>Are you absolutely sure?</DialogTitle>
      <DialogDescription>
        This action cannot be undone. This will permanently delete your account
        and remove your data from our servers.
      </DialogDescription>
    </DialogHeader>
  </Dialog>
</DialogTrigger>

The documented composition is deliberately small and predictable. A trigger wraps the opening button and the Dialog content. Inside the Dialog, the header contains the title and description, and an optional footer can hold the action row. Treat this tree as the default shape for design review and code review: if a dialog lacks a clear title, supporting description, or obvious action placement, users may not understand the temporary task boundary. When a form or editing workflow becomes long, keep the heading in view and consider the scrollable or sticky footer examples instead of building an ad hoc layout. Sources: apps/v4/content/docs/components/aria/dialog.mdx

DialogTrigger
├── Button
└── Dialog
    ├── DialogHeader
    │   ├── DialogTitle
    │   └── DialogDescription
    └── DialogFooter

Dialog and Alert Dialog share the same React Aria Modal documentation link, but their user intent differs. Dialog is a general overlaid window for focused work, while Alert Dialog is described as a modal dialog that interrupts the user with important content and expects a response. Choose Dialog for profile editing, short forms, details panels, or controlled secondary workflows. Choose Alert Dialog when the user must acknowledge risk, confirm destructive behavior, or select between cancel and continue actions before returning to the page. Sources: apps/v4/content/docs/components/aria/dialog.mdx, apps/v4/content/docs/components/aria/alert-dialog.mdx

The Dialog examples cover practical layout variations rather than only a single happy path. A custom close button lets teams replace the default close control with project-specific interaction or iconography. The no close button example uses the showCloseButton false option for cases where explicit in-content actions should control dismissal. Sticky footer keeps actions visible while content scrolls, which is useful for forms with many fields. Scrollable content keeps long body copy manageable while the header remains visible, preserving context during the modal task. Sources: apps/v4/content/docs/components/aria/dialog.mdx

Right-to-left behavior is included as a first-class example rather than an afterthought. The Dialog page points readers to the RTL configuration guide and includes a preview rendered with right-to-left direction. That is consistent with the later preset application note, which says the apply command keeps the current base and RTL settings from an existing project even when a preset URL was generated differently. For teams localizing products, verify both layout direction and close/action placement after installing or reapplying a preset. Sources: apps/v4/content/docs/components/aria/dialog.mdx, apps/v4/content/docs/changelog/2026-04-shadcn-apply.mdx

System-to-Code Mapping

The Dialog page is also a good example of how documentation, registry installation, and customization fit together in shadcn/ui. The MDX file declares the page metadata, renders a component preview named dialog demo using the aria nova style, and exposes both CLI and manual installation paths. The changelog explains that newer registry behavior can resolve files anywhere in an application, track installed files, and perform multi-pass import and alias resolution. That means the documented import path is conventional, but modern registry installation is designed to adapt to real project structure. Sources: apps/v4/content/docs/components/aria/dialog.mdx, apps/v4/content/docs/changelog/2025-04-shadcn-2-5.mdx

The create and apply changelog entries add another layer to this mapping. The create workflow lets users pick component library, icons, base color, theme, fonts, and visual style, and the text says configuration can rewrite component code for spacing, structure, libraries, and other preferences. The Dialog page preview uses aria nova, so readers should not assume every generated Dialog file is visually identical across presets. The stable concept is the composition and accessible modal behavior; visual density, roundedness, icon choices, and generated code details can vary by preset. Sources: apps/v4/content/docs/components/aria/dialog.mdx, apps/v4/content/docs/changelog/2025-12-shadcn-create.mdx, apps/v4/content/docs/changelog/2026-04-shadcn-apply.mdx

API Reference

The Dialog page delegates detailed prop coverage to the React Aria Modal API, while documenting the shadcn/ui level primitives and examples that most application developers use directly. The compact local reference is therefore composition oriented: import the trigger, dialog container, header, title, description, and footer from the local dialog file; optionally disable the close button; and select examples that match the body length and action model. For size-specific modal options, compare the Alert Dialog page, which documents a size prop on AlertDialogContent accepting default or small values. Sources: apps/v4/content/docs/components/aria/dialog.mdx, apps/v4/content/docs/components/aria/alert-dialog.mdx

Surface	Documented role	Notes
DialogTrigger	Connects the opener and dialog content	Wraps the Button and Dialog in the documented usage pattern.
Dialog	The overlaid modal window	Renders while background content is inert according to the page description.
DialogHeader	Groups introductory content	Contains the title and description in the composition tree.
DialogTitle	Accessible title content	Use a clear task title, not decorative text.
DialogDescription	Supporting explanation	Describes consequence, context, or form purpose.
DialogFooter	Action area	Use for submit, cancel, or secondary actions.
showCloseButton	Close-control option	Use false when the example pattern should hide the close button.

Next Steps

After installing Dialog, inspect the generated local component file before treating it as fixed infrastructure. Confirm that imports match the project alias configuration, that any preset or apply workflow has produced the desired visual style, and that the right-to-left configuration is correct for localized products. Use Alert Dialog for interruptive confirmations, especially destructive actions, and keep regular Dialog for focused editing or information workflows. Related reading should include the CLI page for add and apply workflows, the components overview for ARIA family conventions, and the RTL guide when directionality is part of the product requirements.

Ask a question...