Dialog Preview
A dialog is a supplemental surface that can provide helpful interactions or require someone to take an action before they can continue their task, like confirming a deletion.
Dialogs are often interruptions, so use them for important actions. If you need to give someone an update on an action they just took but that they don't need to act on, try a toast. If you need to give someone additional context that doesn't affect their current workflow, try a popover.
Resources
Types
Modal
A modal dialog disables the page content behind it and usually obscures or dims it to surface its content. Use it when someone needs to perform a focused task, like signing into an app.
Non-modal
A non-modal dialog allows someone to continue interacting with the page content behind the window and aids in their workflow, like find and replace. Use it as a helper in a task.
Alert
An alert dialog is a modal that requires someone to make a decision. Alert dialogs have a special role that allows assistive technologies to treat them more urgently than other dialogs, like playing a system alert sound.
Alert dialogs are forceful interruptions. Use them only in cases of potential loss, like unsaved changes or confirming destructive actions.
Behavior
Dismissal
Someone can dismiss a modal dialog by selecting an area outside of the container, using the Esc key, or selecting a footer button. You can include a Close button in the top right of modal dialogs if there is no Cancel button that will close the dialog.
Non-modal dialogs contain a Close button in the top right by default. Someone can dismiss a non-modal dialog by selecting the Close button, using the Esc key, or selecting a footer button. Since non-modal dialogs allow interaction with the content behind them, they can’t be dismissed by selecting an area outside of the dialog.
Alert dialogs can only be dismissed by selecting one of the available buttons in the footer.
Stick with the necessary actions
For best usability, reduce the number of additional keystrokes to exit a modal dialog.
Don’t include redundant options
Including too many actions increases cognitive load.
Dialogs should help people take action, so keep options simple. Overloading dialogs with too many actions might make it harder for people to make a decision and can require extra keystrokes to exit the dialog.
Scrolling
By default, headers (including dialog title and dismiss icon) and footers (including any button actions) will remain persistent at the top and bottom of the dialog container, even on scroll. Overflow body content will scroll behind.
Forms in dialogs
Fields can be placed in dialogs to ask people for information that’s related to their current task. Keep forms within dialogs focused and relevant to the main goal. If dialog forms are too long, people may forget the context of their initial task.
To implement a form in a dialog, include a <Form> element between <DialogSurface> and <DialogBody>. This allows a button in the footer to function correctly as a submission action.
For information on validating forms in dialogs, see the field component.
Layout
Dialogs are laid out in three sections:
- A header, which can contain a title and a dismiss icon
- Optional body content
Optional footer, which can contain up to three actions. If using the dialog without a footer, include an additional 24-pixel padding to the bottom of the container.
Accessibility
Nesting dialogs
Don’t nest dialogs. Selecting an action in a dialog should move people forward in their workflow. Too many dialogs can distract from the original context and make it hard for people with cognitive disabilities or who use magnified views to interact with the content.
Dialog focus
When a dialog is opened, keyboard focus should go to the first interactive element within the container. Modal and alert dialogs trap keyboard focus. People who navigate by keyboard can still interact with the browser by tabbing in and out but won’t be able to access other focusable elements on the page.
Dialogs must have at least one interactive element so that people have a way to exit the dialog without pressing the Esc key or selecting the area outside the dialog.
When the dialog is closed, set keyboard focus back to the component that triggered the dialog.
Content
Communicate the main message in the title
Dialog titles are mandatory and should explain the main information in a clear, concise, and specific statement or question. The title shouldn’t be a description of the body content. For example, don’t use “Error” as a title. Instead, use an informative statement like, “Your session ended.”
Use sentence style capitalization—only capitalize the first word. Don’t use end punctuation unless the title is a question.
Give additional context in the body
Use the body content area for additional info or instructions, if needed. Don’t restate the title in the body. Body content should be actionable, with the most important information at the beginning. If there are consequences to the action, lead with those.
Buttons labels should respond to the title text
Write button labels that are specific responses to the main information in the title. The title “Delete this file” could have buttons labeled “Delete” and “Cancel.” Be concise. Limit labels to one or two words. Usually a single verb is best. Include a noun if there is any room for interpretation about what the verb means. For example, “Delete” or “Delete file.”
Use sentence style capitalization—only capitalize the first word—and don’t use end punctuation. For more info, see Capitalization and Periods in the Microsoft Writing Style Guide.