Dialog

Overview Style Guidelines Code Demos Accessibility

Usage

Use a dialog to communicate critical information that requires input or action. A dialog can be used to validate user decisions, confirm non-destructive or destructive actions, report errors, share task results and statuses, and prompt required user input. A dialog is also interruptive by design. When active, users are blocked from viewing page content and cannot return to their workflow until the dialog task is complete or the dialog is dismissed. A dialog can be effective when used correctly, but it should be used sparingly to limit disruption.

When to use a dialog

A dialog is commonly used for short tasks. If users need to perform a task several times on the same page, consider moving it to the main page instead. Do not use a dialog unless the information or task within is vital to user success and worth disrupting their workflow.

Sizes

There are two dialog container sizes. Choose a size that works best for the amount of available content.

Fixed-width

The fixed-width dialog container works well for environments with a fixed grid, like marketing pages.

A dialog container spanning a 12-column grid that is fixed in the center of the page

Full-width

The full-width dialog container works well for environments with a more fluid grid like apps or dashboards.

A dialog container spanning a 6-column fluid grid that takes up the whole screen

Variants

There are three available dialog variants depending on the intended function.

Confirmation

Use a confirmation dialog to validate user decisions and communicate their consequences. Confirmation dialogs can confirm non-destructive and destructive actions. When confirming a non-destructive action, do the following:

Use a primary button to confirm a non-destructive action
Be specific about what will happen when an action is confirmed

Non-destructive confirmation dialog example with a blue primary button

When confirming a destructive action, do the following.

Use a primary button again or if the action carries serious consequences, use a danger button instead

Destructive confirmation dialog example with a red primary button

Error

Use an error dialog to inform users of problems that interrupt normal or expected behavior. Briefly contextualize the problem, explain why it happened, and then provide actionable steps toward a solution.

Passive

Use a passive dialog to communicate critical and immediately relevant information like the status of an application or the result of an action. When using a passive dialog, consider the following:

Passive dialog content should require or lead to user action
A passive dialog can also notify users about the status or duration of a critical process
Never use a passive dialog for non-critical information, use an inline alert or toast alert instead

Passive dialog example with a blue primary button

Video player dialog

A video can replace a fixed-width dialog container, it should have the same width and include a close button.

A dialog video player spanning a 12-column grid with a white close button

Writing content

Dialog content should be descriptive and specific so users can scan, understand the context of an action, and make a quick decision. A dialog includes three main content sections.

Headline

A headline introduces the purpose of a dialog, sometimes as a question. Use important key words like permanently to describe an action and its consequences.

Body text

Body text provides additional information about the consequence of an action in three lines or less, typically concerning changes to a workflow or access to information. Be mindful of adding interactive elements that would navigate users away from a dialog unless they are crucial yet helpful resources like documentation.

Buttons

Buttons allow users to answer the headline prompt. Write button text labels as verbs to communicate their function and consequence. Button verbs can be pulled from the headline for better scannability.

Character and line counts

The recommended maximum character and line counts for the elements of a dialog are listed below and include spaces.

Element	Character count	Line count
Title text	40	1
Body text	175	2
Button text	30	1

Overflow content

When dialog content is taller than the dialog container height, the body section should scroll vertically with the header and footer remaining fixed in place. The content should visibly fade at the end of the dialog body section to indicate there is additional content out of view. Dialog content should never scroll horizontally.