Dialog

Dialog is a modal that interrupts the user’s workflow and requires them to take an action or dismiss it before they can continue to interact with the page.

Overview

A dialog is triggered by a user’s action and it overlays the page until an action is taken from it or it’s dismissed. Because a dialog interrupts a workflow, it can be disruptive and should be used thoughtfully and only when necessary.

Anatomy

1. Header: Contains a title that describes the intention of the dialog and an affordance to dismiss the dialog.
2. Content: Contains text or other components needed to complete the dialog’s task.
3. Footer: Contains the actions needed to complete the dialog’s task.
4. Overlay: A screen that covers the main page content to focus on the dialog content.
5. Dividers: Lines to separate content from header and footer; only present with scrolling content.

Demo

Open the component in Figma.

When to use

Use a dialog in the following scenarios:

• When you need to ask a user to confirm an action they want to take.
• When you need to share important information that a user needs to acknowledge.
• When you need to tell a user that if they proceed with an action they’ve initiated, it may impact their data in a negative way.
• When you need to communicate critical information about an issue that a user needs to resolve before they can continue with a task.

When not to use

Don’t use a dialog in the following scenarios:

• When there is an existing dialog; so you have a dialog on top of another dialog.
• When content doesn’t require immediate action.
• When additional information needs to be consulted outside the dialog.
  - While a dialog is active, a user can’t interact with the main page and is restricted to only the information in the dialog to make decisions.
• When you have complex or long-form content. Use a new page instead.
• When you need a system-initiated message. See banner.

Behaviors

Arrival

A dialog should be initiated by the user. For example, clicking a button that triggers it to open provides the right context for a dialog that can be disruptive to their workflow.

System-initiated dialogs need to be avoided because the user doesn’t know why the page is being obscured and they can be confused.

Dismissal

Dismissing a dialog undoes any applied changes and returns the user to the previous page. The dialog can be closed with any of the following actions:

• Clicking the close icon button (X) in the header
• Clicking the Cancel button in the footer
• Pressing the esc key on the keyboard.
• Clicking in the overlay outside of the dialog.

Autofocus

Focus is placed on the first item a user can select, allowing them to immediately exit or submit the dialog when possible. Focus is limited to the scope of the dialog while the dialog is open.

Overflow

When the content of a dialog is longer than its height, the content area will scroll vertically while the header and the footer remain fixed.

Accessibility

Odyssey components are designed and built to meet accessibility requirements out of the box. So, designers and engineers can focus on any accessibility concerns unique to their problem areas.

Our components meet WCAG 2.2 AA criteria and WAI-ARIA guidelines to provide a usable and accessible experience to everyone. See the ARIA guidelines for dialog.

Content guidelines

Title

• A title is required.
• Summarize the decision required using a verb + noun combination that clearly describes the dialog’s task or purpose. For example, Erase USB storage.
• Provide a sense of connection between the action that triggers the dialog and the dialog itself to create a consistent user experience. For example, use the same verb as the button that triggers the dialog.
• Don’t ask questions such as, Are you sure you want to quit? or Do you want to cancel?
• Questions are redundant and undermine a user's agency in the decision they've already made to get to the dialog.
• Questions set up a yes/no set of actions, which can become confusing.
• Write in sentence case (capitalize the first word and proper nouns only).
• Don’t use punctuation at the end of the title.

Body copy (optional)

• Provide concise, actionable additional information or context that a user needs to know to make one of the decisions offered by the actions.
• Be direct; include only content relevant to making the decision the dialog requires.
• Use complete sentences.
• Put the most critical information first.
• If the body copy is longer than the height of the dialog, it will automatically scroll.

Do

Confirmation dialogs require users to explicitly confirm their choice before an option is committed.

Don't

Use a confirmation dialog to ask a question that reiterates the choice users made to trigger the dialog. Focus on the result.

Do

Confirmation dialogs can require users to explicitly confirm their choice before an option is committed.

Don't

Confirmation dialogs generally don't need multiple confirmations within the same dialog. While deletions are permanent, there is a risk in making a confirmation modal seem so serious and consequential, that users are afraid to change anything.

Primary button text

• Explain what the button will do with a verb + noun to describe the result.
• Use the same verb as the title if possible. For example,  if a dialog's title is Delete rule, its primary button label would be Delete.
• If the dialog contains an acknowledgment, only the primary button is used.

- Default label: OK

Secondary text button label

• Provide an option to go back or cancel the action.

- Default label: Cancel

• The secondary button can be omitted if the dialog is an acknowledgment.

Content accessibility

Use the title text to label the dialog element with aria-labelledby. This helps to convey the purpose of the dialog to screen reader users when it displays.

Figma: Dialog