v1.0.0 | View in Storybook
When to use
- Focused tasks: Short forms, template selection and quick settings adjustments.
- Secondary content: Image zoom-ins, detailed information, video playback.
When to use something else
- Non-blocking messages that don’t require immediate action: use Sonner, Banner, or Alert (context-dependent).
- Important messages requiring immediate attention or blocking confirmation: use Alert dialog.
- Comparative workflows: use a drawer or side panel if the user must compare information without losing surrounding context.
- Complex or multi-step flows: use a dedicated page or wizard if the input is too heavy for a Dialog.
- No need to interrupt flow: use inline patterns such as Accordion or Collapsible.
Alert dialog vs Dialog
A Dialog is a flexible, interactive modal used for routine tasks like editing forms, viewing detailed information, or completing multi-step workflows. An Alert dialog is an interruptive, high-priority modal specifically designed for critical or destructive decisions (such as deleting data), halting user workflow until an explicit choice is made.
Dos and don’ts
- Do ensure users can easily dismiss the Dialog. Always include a cancel Button and close icon Button.
- Do trap focus within the Dialog for accessibility. Users should not be able to interact with the background content.
- Do include top and bottom Separators only if the content within the Dialog is scrollable.
- Do maintain the default center placement for all Dialogs. Alternative placements should be avoided unless there is a specific, justified use case.
- Do use a transparent overlay background behind the Dialog.
- Don’t interrupt the user unnecessarily - only use Dialogs when it’s important to interrupt.
- Don’t change the position of the primary call to action. It should always be positioned furthest right.
- Don’t stack multiple Dialogs or nest them.
- Don’t use a Dialog size that’s larger than necessary. There should not be a ton of white space around form or text elements.
Behavior
- Dialog variant blocks interaction with the page behind it until dismissed; focus is trapped inside the dialog while open.
- Escape and an explicit dismiss control (cancel, close) should return focus to a sensible element (typically the trigger).
- Only one Dialog should stack at a time; do not nest Dialogs.
Often used with
Footer Buttons (primary right); Separator for scrollable bodies; form fields (Input, Select, Textarea, etc.); optional inner Tabs for rare complex modals.
Accessibility
Labeling and semantic markup
- Keep DialogTitle rendered: If your design omits a visual header, wrap
<DialogTitle> in an accessibility class (e.g., className="sr-only") rather than removing the element.
- Provide or explicitly suppress DialogDescription: If your dialog lacks body text, pass
aria-describedby={undefined} to <DialogContent> to prevent browser console warnings and avoid broken ARIA references.
- Label icon-only triggers: If
<DialogTrigger> wraps an icon-only button, ensure the button carries an explicit aria-label or accessible name.
Focus and flow management
- Override destructive initial focus: By default, focus moves to the first focusable element inside the content. For dangerous actions, override initial focus to target the safest action (e.g., “Cancel”) by calling
e.preventDefault() inside onOpenAutoFocus and focusing the designated element.
- Handle deleted triggers on close: If closing the dialog deletes the original trigger element (e.g., deleting a table row item), focus will drop to
<body>. Use onCloseAutoFocus to direct focus to a logical fallback, like the table container or next list item.
- Form error focus: If the dialog contains a form that fails validation, explicitly shift focus to the first invalid field or an error summary banner so screen reader users are notified instantly.
Visual examples
The examples below are interactive and follow the doc site’s theming: light mode when the docs site is in light mode, and dark mode when you switch the docs site to dark mode.
Use a Dialog with a form when you need a short, focused data-entry flow—such as creating a record or editing settings—without navigating away from the current page.
Omit the close button on a Dialog only when dismissal must go through explicit actions—for example, a required choice or a multi-step flow where cancel is provided in the footer.
Controlled
Use a controlled Dialog when open and closed state must follow application logic—for example, opening from multiple triggers or closing after an async action completes.
Scrolling content
Use a Dialog with scrolling content when the body exceeds the viewport, adding Separators at the top and bottom of the scroll region so the header and footer stay fixed.
Non modal
Use a non-modal Dialog when the user should interact with both the dialog and the page behind it—for example, a reference panel or inline assistant that does not block the main workflow.
Nested
Avoid nesting Dialogs in production; this example exists to document stacking behavior when a secondary prompt must appear over an already-open Dialog.
Title only
Use a title-only Dialog for simple confirmations or alerts where a short heading is enough and no description paragraph is needed.
Use the long-header Dialog pattern when the title or description may wrap to multiple lines, ensuring the header layout stays readable without crowding the close control.
Add a back button to the Dialog header when the flow has a previous step—for example, moving from a list view to a detail form inside the same modal.
Confirmation
Use a confirmation Dialog when the user must acknowledge an action before it proceeds—for example, saving changes or applying a bulk update.
Async action
Use an async-action Dialog when the primary button triggers a server request, disabling actions and showing progress until the operation finishes or fails.
Last modified on September 16, 2026
