# Dialog

A modal window that overlays the page and traps focus.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available by appending `.md` to any URL or sending an `Accept: text/markdown` header. An agent skill is available at [/.well-known/agent-skills/site-skill.md](/.well-known/agent-skills/site-skill.md).

<DocsBaseSwitcher base="web" component="dialog" />

<ComponentPreview name="dialog" title="dialog.tsx">
<Component />
</ComponentPreview>

Dialog renders a modal that overlays the page and traps focus until dismissed.

## Installation [#installation]

<CodeTabs>
<TabsList>
<TabsTrigger value="cli">
Command
</TabsTrigger>

<TabsTrigger value="manual">
Manual
</TabsTrigger>
</TabsList>

<TabsContent value="cli">
~~~bash
npx frakment add dialog
~~~
</TabsContent>

<TabsContent value="manual">
<Steps>
<Step>
Install the following dependencies:
</Step>

~~~bash
npm install lucide-react
~~~

<Step>
Copy and paste the following code into your project.
</Step>

<ComponentSource name="dialog" title="components/ui/dialog.tsx" />

<Step>
Update the import paths to match your project setup.
</Step>
</Steps>
</TabsContent>
</CodeTabs>

## Usage [#usage]

~~~tsx title="dialog.tsx"
import {
  Dialog, DialogClose, DialogContent, DialogDescription,
  DialogFooter, DialogHeader, DialogTitle, DialogTrigger,
} from "@/components/ui/dialog";
~~~

~~~tsx
<Dialog>
  <DialogTrigger as={Button}>Open</DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Title</DialogTitle>
      <DialogDescription>Description</DialogDescription>
    </DialogHeader>
    <DialogFooter>
      <DialogClose as={Button} variant="outline">Cancel</DialogClose>
      <Button>Save</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>
~~~

## Composition [#composition]

```text
Dialog
├── DialogTrigger
└── DialogContent
    ├── DialogHeader
    │   ├── DialogTitle
    │   └── DialogDescription
    ├── DialogFooter
    └── DialogClose
```

## Examples [#examples]

### With close button [#with-close-button]

A dialog with an inline Close button instead of the corner X.

<ComponentPreview name="dialog-close-button" title="dialog-close-button.tsx" src="examples/dialog-close-button.tsx" previewClassName="h-auto py-8">
<l />
</ComponentPreview>

### Without close button [#without-close-button]

Pass `showCloseButton={false}` and dismiss via backdrop or Escape.

<ComponentPreview name="dialog-no-close-button" title="dialog-no-close-button.tsx" src="examples/dialog-no-close-button.tsx" previewClassName="h-auto py-8">
<d />
</ComponentPreview>

### Sticky footer [#sticky-footer]

Scrollable body with a footer that stays pinned to the bottom.

<ComponentPreview name="dialog-sticky-footer" title="dialog-sticky-footer.tsx" src="examples/dialog-sticky-footer.tsx" previewClassName="h-auto py-8">
<c />
</ComponentPreview>

### Scrollable content [#scrollable-content]

Long content scrolls inside the dialog without growing it past the viewport.

<ComponentPreview name="dialog-scrollable-content" title="dialog-scrollable-content.tsx" src="examples/dialog-scrollable-content.tsx" previewClassName="h-auto py-8">
<o />
</ComponentPreview>

## In Context [#in-context]

### Confirm deletion [#confirm-deletion]

<ComponentPreview name="dialog-confirm" title="dialog-confirm.tsx" src="examples/dialog-confirm.tsx">
<DialogConfirm />
</ComponentPreview>

## Data Attributes [#data-attributes]

| Attribute | Values | Applies to |
| :-- | :-- | :-- |
| `data-slot` | `dialog-trigger`, `dialog-content`, `dialog-header`, `dialog-footer`, `dialog-title`, `dialog-description`, `dialog-close` | Per sub-component |
| `data-state` | `open` \| `closed` | `Dialog`, `DialogContent`, `DialogOverlay` |

Use these in CSS or tests to target the current state:

```tsx
<DialogContent className="data-[state=open]:opacity-100 data-[state=closed]:opacity-0" />
```

## Keyboard [#keyboard]

| Key | Action |
| :-- | :-- |
| `Esc` | Close the dialog |
| `Tab` | Move focus forward |
| `Shift + Tab` | Move focus backwards |
| `Enter` / `Space` | Activate focused element |

Focus is trapped inside `DialogContent` while open. On close, focus returns to the trigger.

## Controlled [#controlled]

Without `open`, the dialog manages its own state. Pass `open` and `onOpenChange` to control it:

```tsx
const [open, setOpen] = React.useState(false)

<Dialog open={open} onOpenChange={setOpen}>
  <DialogTrigger as={Button}>Open</DialogTrigger>
  <DialogContent>{/* ... */}</DialogContent>
</Dialog>
```

Use `defaultOpen` for an uncontrolled dialog that starts open.

## As Prop [#as-prop]

`DialogTrigger` and `DialogClose` accept an `as` prop to render a custom element:

```tsx
<DialogTrigger as={Button} variant="outline">Settings</DialogTrigger>
```

Without `as`, the trigger renders as a native `<button>`.

## Motion [#motion]

`DialogContent` accepts a `motion` prop to customize the entrance and exit timing:

```tsx
<DialogContent motion="200 ease-out">{/* ... */}</DialogContent>
```

The default is `150ms ease-out`. `motion="off"` disables the animation. `prefers-reduced-motion` is always respected.

## API Reference [#api-reference]

### DialogContent [#dialogcontent]

<PropsTable rows={[{"name":"showCloseButton","type":"boolean","default":"true","description":"Show the top-right close button."},{"name":"motion","type":"string","default":"150ms ease-out","description":"Entrance/exit timing. Set to off to disable."},{"name":"className","type":"string","description":"Extra classes on the modal panel."}]} />

## Accessibility [#accessibility]

- Focus is trapped inside the dialog while open.
- `DialogTitle` and `DialogDescription` are announced to screen readers via `aria-labelledby` and `aria-describedby`.
- `Escape` closes the dialog.
- Clicking the backdrop closes the dialog.
- `role="dialog"` and `aria-modal="true"` are set on `DialogContent`.

## Best Practices [#best-practices]

- **Do not use a dialog for navigation.** Use a sheet or a new route instead.
- **Keep content short.** If it needs to scroll, it might belong on its own page.
- **Provide multiple exits.** Cancel in the footer, Escape key, and outside click.
- **Put the destructive action last.** Primary on the right, destructive on the far right.

## Related Components [#related-components]

- [Sheet](/docs/components/sheet) — modal panel that slides in from an edge
- [Dropdown Menu](/docs/components/web/dropdown-menu) — action menu anchored to a trigger
- [Tooltip](/docs/components/web/tooltip) — short hint on hover