Dialog
A modal or explicitly modality-declared overlay that interrupts the page for a focused task.
Anatomy
| Part | Required | Description |
|---|---|---|
backdrop | yes | Dimmed or blocking layer behind the surface. |
surface | yes | Dialog container. |
title | yes | Accessible and visible title. |
description | no | Supporting explanation. |
content | no | Main body content. |
actions | no | Action buttons such as confirm and cancel. |
close | no | Explicit close control. |
States
- default
- open
- opening
- closing
- closed
Keyboard
- Initial focus moves to the element declared by the focus contract when the dialog opens
- Tab cycles inside the focus trap while open
- Escape dismisses when escape dismissal is enabled
- On close, focus restores to the previously focused trigger
Accessibility
Modal dialogs must trap focus while open, set initial focus deliberately, allow Escape and/or backdrop dismissal when those mechanisms are part of the contract, and restore focus to the invoking control on close. Provide an accessible name from the title and optional description relationship. Do not leave inert background content reachable by keyboard or assistive technology while the modal is open.
Motion
Entrance may fade and scale the surface; under reduced motion, show the settled open state without springy motion while keeping focus behavior intact.
Platform mappings
web
Native HTML dialog or ARIA dialog/alertdialog with documented focus management.
apple
SwiftUI confirmationDialog/sheet/alert matched to modality; UIKit UIAlertController or modal presentation.
android
Compose Dialog or AlertDialog with back-handler dismissal aligned to the contract.