When to Use
Example: product shelf + Quick view dialog (decorative)
- Confirming destructive or irreversible actions (e.g. delete, discard changes)
- Collecting short-form input that must be completed before proceeding
- Presenting supplementary content in a side panel (Sheet) without leaving the current view
- Showing a compact product summary from a listing (Quick view) without navigating to PDP
- Avoid dialogs for long or complex forms — use a dedicated page instead
Usage Guidelines
DO
Keep titles concise and use red confirm buttons for destructive actions. Always provide a cancel/close path
Don’t
Don't nest dialogs — use a multi-step flow instead
DO
Keep forms inside dialogs simple (≤ 3 fields)
Don’t
Don't show large amounts of content in a dialog — use a separate page. Don't use dialogs for non-urgent information — use Toast instead
DO
Always provide a way out — keep at least one exit path (close button, cancel, or Escape)
Don’t
Don't disable all closing paths — users need a way out. Don't show large amounts of content in a dialog — use a separate page
Interaction Behavior
| State | Description |
|---|---|
| Open | Overlay fades in + dialog scales up from center; focus moves to first interactive element |
| Content interaction | Focus is trapped inside dialog (focus trap), Tab cycles within |
| Click overlay | Closes dialog (when closable=true) |
| Escape | Always available, closes dialog |
| Close | Animation reverses; focus returns to trigger element; page scroll resumes |
Accessibility
| Requirement | Implementation |
|---|---|
| Semantic role | role="dialog" + aria-modal="true" |
| Title association | aria-labelledby linked to the title element ID |
| Content description | aria-describedby linked to the body |
| Focus trap | Tab cycles within the dialog; cannot escape |
| Focus restoration | Focus returns to the trigger button on close |
| Scroll lock | Disables <body> scroll on open (overflow: hidden) |