# Modal

Modal places a focused task above the current page and returns focus when the task closes.

Choose kind="dialog" for a short task or form that needs page context. Choose kind="confirmation" for a consequential choice with explicit Cancel and Confirm actions. On narrow screens, the dialog uses the available viewport width and keeps its fields contained.

<h2 id="purpose">Purpose</h2>

Use Modal for short decisions and forms that need page context. Set `kind` on every Modal. Use `dialog` for forms and short tasks. Use `confirmation` only when the user must explicitly accept or cancel a consequential decision. Move long or navigable work to a page or Sheet.

<h2 id="anatomy">Anatomy</h2>

Modal combines a consumer-owned trigger, dialog surface, title, description, content, and optional footer actions. The `trigger` snippet receives delegated props; spread them onto its one real interactive element. `kind="dialog"` uses Dialog behavior for forms and tasks. `kind="confirmation"` uses alert-dialog semantics and explicit Cancel and Confirm actions for consequential decisions. Bind the open state when application code must close the dialog after a save. Give every Modal a task-specific title and add a description when the consequence needs context. The dialog keeps focus inside its surface, closes with Escape when dismissible, and restores focus after closing.

<h2 id="tokens">Tokens and style hooks</h2>

Modal uses surface, border, shadow, radius, overlay, motion, and floating-layer tokens. A scoped `Provider` keeps its portal inside the active boundary.

## API

The package declarations define these public members.

### Inherited prop contracts

- `Omit<ModalBaseProps, 'title'>` — Props from this native base are accepted except the listed members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `cancelLabel` | `string` | prop | No | `'Cancel'` | No additional description. |
| `children` | `Snippet` | snippet | No | `undefined` | No additional description. |
| `closeLabel` | `string` | prop | No | `'Close'` | No additional description. |
| `confirmLabel` | `string` | prop | No | `'Continue'` | No additional description. |
| `confirmVariant` | `ModalConfirmVariant` | prop | No | `'primary'` | No additional description. |
| `description` | `string` | prop | No | `undefined` | No additional description. |
| `dismissible` | `boolean` | prop | No | `true` | No additional description. |
| `footer` | `Snippet` | snippet | No | `undefined` | No additional description. |
| `kind` | `'confirmation' \| 'dialog'` | prop | Yes | - | No additional description. |
| `onCancel` | `() => void` | callback | No | `undefined` | No additional description. |
| `onConfirm` | `() => void` | callback | No | `undefined` | No additional description. |
| `open` | `boolean` | binding | No | `false` | No additional description. |
| `size` | `ModalSize` | prop | No | `'md'` | No additional description. |
| `title` | `string` | prop | No | `undefined` | No additional description. |
| `trigger` | `Snippet<[Record<string, unknown>]>` | snippet | No | `undefined` | No additional description. |

## Related

- [CommandPalette](/docs/components/command-palette): Searchable command dialog with grouped results.
- [Sheet](/docs/components/sheet): Edge-anchored dialog panel with optional body padding.
- [Menu](/docs/components/menu): Dropdown action menu with declarative items and eyebrow-styled group headers.