---
url: https://brand.okrado.com/patterns/dialog/
title: Dialog
description: "A modal for a focused task or a form: when to use it, and how it behaves."
kind: reference
owner: hmdmsd
updated: 2026-11-03
review_by: 2027-02-28
audience:
  - designer
  - developer
  - agent
---

# Dialog

> A modal for a focused task or a form: when to use it, and how it behaves.

Use a dialog for a short task that needs the person’s full attention: a form of a few fields, or reading something before continuing. It interrupts, so do not use it for information the page can show in place. For a decision that cannot be taken back, use the [alert dialog](https://brand.okrado.com/patterns/alert-dialog/). For a long record or a multi-step flow, use a [drawer](https://brand.okrado.com/patterns/drawer/).

## Behaviour

Read from the component manifest, so this is the component’s own contract. See [Overlays](https://brand.okrado.com/patterns/overlays/) for layers, stacking and dismissal shared by all layers.

### `Dialog`

| Stage         | beta                                                                                                                                                                                                                   |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Keyboard      | - Tab and Shift+Tab loop inside the dialog
- Escape closes it (guarded while dirty)
- Enter or Space presses the focused button                                                                                        |
| Dismissal     | * escape: yes, guarded when dirty
* outside press: informational only
* close button: yes, guarded when dirty
* back gesture: yes, guarded when dirty                                                                  |
| Stacking      | Opens over a drawer; only an AlertDialog opens over it; an AlertDialog may be a terminal third layer; no other third modal.                                                                                            |
| Accessibility | - Focus moves into the dialog, is trapped there and returns to the trigger on close; Escape closes it; the page behind is inert and does not scroll. Under 640 px it fills the screen, and the Back gesture closes it. |
| Pattern       | [APG: dialog modal](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)                                                                                                                                            |
| Docs          | [Storybook](https://brand.okrado.com/components/?path=/docs/primitives-dialog--docs)                                                                                                                                   |

### `DialogContent`

| Stage         | stable                                                                                                                                                                                                           |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Accessibility | - `role="dialog"` named by `title` and described by `description`; the close button's name comes from the shared catalog; a body that scrolls becomes a labelled, focusable region so the keyboard can reach it. |
| Docs          | [Storybook](https://brand.okrado.com/components/?path=/docs/primitives-dialog--docs)                                                                                                                             |

### `DialogTrigger`

| Stage         | stable                                                                               |
| ------------- | ------------------------------------------------------------------------------------ |
| Accessibility | - Gets `aria-haspopup="dialog"` and `aria-expanded`.                                 |
| Docs          | [Storybook](https://brand.okrado.com/components/?path=/docs/primitives-dialog--docs) |

### `DialogClose`

| Stage | stable                                                                               |
| ----- | ------------------------------------------------------------------------------------ |
| Docs  | [Storybook](https://brand.okrado.com/components/?path=/docs/primitives-dialog--docs) |