Dialog Guidelines

The Dialog component displays a modal window floating over the page's layout.

Design Guidelines

Dialogs are displayed over the page, so they can be used to show extra content without affecting the layout itself (unlike Accordions).

Dialogs make the workflow less linear, as you have to "get in then get out", so they're better used for creating optional branches that are not part of a linear flow (except confirmation dialogs).

As Dialogs display a modal window with limited space, it's best to use them for simple, specific purposes, such as filling in a short form, previewing data, or prompting the user to make a decision.
Modal means the user will be put into a "mode", so they won't be able to interact with the rest of the UI until they exit the "mode" (closing the Dialog). This is indicated by displaying an Overlay between the page and the Dialog.

The Dialog can be closed by clicking outside the Dialog, clicking the Close Button, or pressing the escape key.

Dialogs should be sized so its content is accessible without scrolling, as "letterbox scrolling" is bad for usability.
If the content is too much to be fully displayed in a Dialog, consider using a different pattern for displaying the UI (e.g. Accordion, Steps).

Placement

Dialogs are displayed in the middle of the screen.

Content

Title: keep titles short and to the point. For more info, check the UI Text Guidelines.

Buttons: Buttons are displayed in the footer, and the group is aligned to the right side of the footer. In the group, the Highlighted Action is displayed first on the left. Avoid displaying more than 3 buttons in the footer.

Back button: for workflows that include a linear sequence of dialogs, the Dialog can display a Back Button in its header, similar to the Back Button in the page's header.

Cover images: an image can be displayed at the top of the Dialog, seamlessly reaching behind the header, using the "cover image" feature. You can switch between dark and light text and icon colors for the header to make sure they remain visible over the cover image.

Custom UI in header and footer: display extra content (such as buttons, labels, or text) by the default Dialog header and footer content using the "slots" feature. Check the code examples and API documentation for more info.

Accessibility

Our Dialog component supports keyboard navigation: you can open the Dialog, close the Dialog with the escape key, and tab between actions inside the Dialog using the keyboard.

Tabbing is looped for actions inside the Dialog until the Dialog is closed.

Use-Cases

Confirmation Dialogs

Confirmation dialogs is a pattern for Dialogs to act as a “final prompt” before committing to an action, and as a safety measure against accidental inputs.

The title should be framed as a short, easy-to-comprehend question, and the user answers this question by clicking a button, e.g. "Delete This?" with the buttons "Delete" and "Cancel".

Text content in these dialogs should elaborate on the effect of the action, e.g. "Once deleted, the campaign “newsletter 171206” cannot be accessed, sent to recipients, or used in automation workflows anymore.".

The Highlighted Action should be labelled as the action ("Delete" or "Send"), instead of a generic response like "Yes" or "OK".

Consequential Confirmation

In general, a consequential confirmation should be displayed before the user commits to an action which will result in consequences that are hard to stop or undo, e.g. creating a large number of resources, launching a campaign, starting a process that will take a long time to finish, triggering an action that affects a large number of contacts, etc.

Example:

“Create Birthday Program?
The program you are about the create will generate Automation programs, Campaigns and Segments. This might take a few minutes.
Create Program, Cancel”

Delete Confirmation

The delete confirmation should be displayed before the user permanently deletes a resource.

This dialog communicates the permanence of the destructive action, and acts as a safety measure against accidental deletions.

Make sure to use a label for the Highlighted Action Button so it conveys the destructivity, even if the user doesn't read the rest of the dialog!

Examples:

“Delete This?
Once deleted, it cannot be accessed anymore.
Delete, Cancel”

“Delete Campaign?
Once deleted, the campaign “newsletter 171206” cannot be accessed anymore.
You will not be able to send it to recipients.
You will not be able to use it in automation workflows.
Delete, Cancel”

Discard Confirmation

The discard confirmation should be displayed when the user wants to leave a page or close a dialog in which they have unsaved data, and navigating away will discard that data.

Examples:

“Discard Changes?
By closing this dialog, all your unapplied changes will be lost.
Discard, Cancel”

“Discard Changes?
By leaving this page, all your unsaved changes in the campaign “newsletter 171206” will be lost.
Discard, Cancel”