---
title: "Dialog"
description: "A modal dialog for confirming or editing without leaving the page. It traps focus, closes with Escape and returns focus to the trigger."
kind: component
id: C-031
registry: "dialog"
docs: "https://koten.codehive.com.co/components/dialog"
markdown: "https://koten.codehive.com.co/md/components/dialog.md"
install: "npx shadcn@latest add https://koten.codehive.com.co/r/dialog.json"
language: en
---

# Dialog · ダイアログ

> Component C-031 in the Koten UI catalog.

A modal dialog for confirming or editing without leaving the page. It traps focus, closes with Escape and returns focus to the trigger.

> Japanese labels in this page are documentation metadata. Keep the consumer UI in the product's language and do not add Japanese decoration unless the user asks (R-031).

## Install

Install `koten-theme` first when the project does not have Koten tokens yet. Use the runner of your project.

```bash
# Node
npx shadcn@latest add https://koten.codehive.com.co/r/dialog.json

# Bun
bunx shadcn@latest add https://koten.codehive.com.co/r/dialog.json
```

## Files

- `@/components/ui/dialog.tsx`
- `@/lib/koten/cn.ts`
- `@/lib/koten/format.ts`
- `@/lib/koten/intl.ts`
- `@/lib/koten/labels.ts`
- `@/lib/koten/provider.tsx`

## Requirements

- **portal** — Portaled popup: The popup mounts inside BaseDialog.Portal, outside the document flow. Do not nest it in containers with overflow or in layers with their own z-index.

## Reference

- Upstream primitive: https://base-ui.com/react/components/dialog

## Examples

### Confirmation with footer

Title, description and a footer with actions; the close control is appended at the end of the footer.

```tsx
<Dialog
  trigger={<Button variant="primary">Open dialog</Button>}
  title="Order details"
  description="KURA-0142 · KURA Distribution"
  closeLabel="Close"
  footer={
    <>
      <Button variant="ghost">Cancel</Button>
      <Button variant="primary">Save changes</Button>
    </>
  }
>
  <p>The order leaves the Tokyo warehouse on 22 Oct.</p>
</Dialog>
```

### Without actions

Without a footer the dialog only informs; the header button still closes it.

```tsx
<Dialog
  trigger={<Button variant="outline">View note</Button>}
  title="Stock note"
  description="Written by the Osaka warehouse team"
  closeLabel="Close"
>
  <p>Reserved units are held for 48 hours.</p>
</Dialog>
```

## Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `trigger` | `ReactElement` | `—` | The element that opens the dialog; Base UI merges its props with the trigger. |
| `title` | `ReactNode` | `—` | Required: BaseDialog.Title provides the accessible name. |
| `description` | `ReactNode` | `—` | Optional; it is associated with the dialog as its description. |
| `children` | `ReactNode` | `—` | The dialog body, inside the scrollable area. |
| `footer` | `ReactNode` | `—` | Footer actions; the close button using closeLabel is appended at the end. |
| `closeLabel` | `string` | `—` | Accessible text for the close control in the header and footer. |
| `className` | `string` | `—` | Merged with the default max width and border. |

## Accessibility

- The name comes from title and the context from description; in practice both are required.
- Focus stays trapped in the popup; Escape, the close button and the backdrop close it.
- On close, focus returns to the element that opened the dialog.
- While open, the rest of the page is removed from the keyboard order.

## Sources

- Catalog page: https://koten.codehive.com.co/components/dialog
- Markdown: https://koten.codehive.com.co/md/components/dialog.md
- Repository: https://github.com/codehive-colombia/koten