Usage guidelines outline how the component should and shouldn’t be used in different user interface contexts.
When to use
- To communicate an important warning in order to prevent or correct critical errors
- To request the user to enter information critical to continuing the current process
- To guide users through a task step by step and/or provide additional information in a side panel
When not to use
- To present non-essential information unrelated to the current user flow, thus unnecessarily interrupting the user
- For complex decision-making that requires the user to consult additional sources of information (potentially blocked by the Dialog), show the content on the page instead of in an overlay.
Best practices
Do use a dismiss (“x”) button for non-confirmation dialogs (e.g., create, edit, upload, upsell). These types of dialogs are low risk and can be dismissed at any time without a decision.
Don't use a dismiss (“x”) button for confirmation dialogs (unsaved changes, delete), which can generally have a destructive outcome. The user makes a serious decision here, so we make the choices explicit.
Do choose an appropriate container size. Dialogs with minimal content are better suited to a small width. Larger widths (medium and large) display heavier amounts of content more legibly.
Be careful when writing titles and descriptive copy. Use the pre-defined templates where available; otherwise, follow our Writing guidelines and keep them concise.
Do use the pre-defined copy for specific Dialogs, such as “Unsaved changes”, including the title, description, and button copy.
Don’t change the copy in pre-defined templates, including the title, description, and button copy. If using the generic template, avoid writing a title that wraps over two lines.
Don’t use an icon in the title. If you need to grab the user’s attention with a warning or error, use the leading icon next to the subtitle, or an Inline Message.
Do use inline validation in a form (when a server-side task fails and client-side validation is triggered).
Do ensure that alt text is provided for the imagery.
Do use a dark illustration for the dark theme. If you only create one asset, use a dark illustration for both themes.
If using a Test Button, do add it to the main content. It should not be included in the footer actions.
Don’t write so much copy for the side panel that it requires scrolling. Follow our Writing guidelines and keep the content concise.
Do use a Dialog with a single step or multiple steps.
Be careful when using many steps to complete a dialog flow. Aim to use no more than 3 steps. If more steps are required, show the content on a page instead.
If using a Progress Tracker, do place it below the title area and above the rest of the dialog content.
Don’t use an Actionable Callout in a Dialog. If you need to grab the user’s attention with a warning or error, use the leading icon next to the subtitle, or an Inline Message.
