Home

Dialog

UsageDevelopment

About

A Dialog is a pop-up window that prompts users with high importance information or requires users to take action. Users need to interact with a Dialog before they can proceed with the main content in the background.

Anatomy

A Dialog may exist of three slots:

  1. Header: a header is the top area of a Dialog. A header allows for a headline and has a mandatory close icon.
  2. Body: a body is the middle area of a Dialog. This is were a Dialog’s content lives. The content is fully customisable. A scroll container and bar might be added if the content makes a Dialog exceed the maximum width.
  3. Footer: a footer is the bottom area of a Dialog. A footer allows for buttons to allow users to take actions. A footer is not mandatory, since a Dialog may also be used for just sharing (critical) information.

Dialog slots

Looking at the anatomy details, a Dialog exists of the following mandatory and optional elements:

  1. Container
  2. Close icon
  3. Headline
  4. Body text (optional)
  5. Buttons (optional)
  6. Background overlay

Dialog anatomy

When to use a Dialog

Dialogs should be used for:

  • Informing users about errors that block an apps’ operation;
  • Requesting users for critical information that specifically requires their response or input.

When not to use a Dialog

Behaviour

Variants

There are 3 different variants of a Dialog:

  1. Informative Dialog: this variant should be used for communicating critical information to users without the need for them to take any action. The only action that users can perform is closing a Dialog. There’s no need to use the footer slot in this variant.
  2. Confirmation Dialog: this variant allows users to provide input and then confirm or confirm something right away. The body slot would contain the information and/or input fields to enter data. The footer slot would contain buttons to take action such as confirming or canceling.
  3. Multistep Dialog: this variant should be used for Dialogs that need one or several extra steps, allowing users to go back and forth between those steps. It’s important that all slots are used (header, body, footer) and better alternatives are researched (e.g., full page) because of accessibility.

Dialog variants

Multistep best practices

  • Make sure each step uses the same Dialog size;
  • The Back/Next button pattern should be used, which means it will be Secondary button/Primary button.

A Dialog always behaves modal. This means that a Dialog gets a background overlay indicating to users they cannot interact with the main content until the notification is closed.

Scroll behaviour

The body slot of a Dialog automatically gets scroll behaviour if the body content makes the height of a Dialog exceed. This means a native scroll bar will be visible. Users will be able to interact with this scroll bar to scroll down for more content.

Keyboard behaviour

  • Users would be able to navigate through the interactive elements within a Dialog by pressing the Tab key and Arrow keys;
  • Users would be able to close a Dialog by focusing on the close icon and press the Enter key;
  • Users would be able to scroll through the body content with the focus on the scrollbar and using the Up and Down keys.
  • Esc key

If there’s no input needed (informative variant) or provided yet, users are able to close a Dialog by pressing the Esc key. However, to ensure users won’t loose input, a Dialog cannot be closed by pressing the Esc key (by accident) when users have provided input already.

Size & placement

The width of a Dialog component spans between 375 - 800 px. You can use the default sizes to keep Dialogs in your UI more consistent. If needed you can adjust this as well, as long as the width is between this min-max span.

The height of Dialogs is flexible to their content but should not go over its max limits.

Small

Width: 375 px, Height: depending on content (max 250 px):

Dialog-size-small

Medium

Width: 600 px, Height: depending on content (max 600 px):

Dialog-size-medium

Large

Width: 800 px, Height: depending on content (max 720 px):

Dialog-size-large

Figma usage

A Dialog in our Figma library can hold regular text or it can be used together with slot components, which will let you (designers) add their custom local components. For example, you can add a form as their content to place inside a Dialog.

Content

Headline

The headline should be short and convey a clear message.

Do write clear headlines
Do write clear headlines.
Do

Don’t write general, unclear headlines
Don’t write general, unclear headlines.
Don’t

Button labels

The button labels should allow users to understand the result of their action right away.

Do write clear button labels
Do write clear button labels.
Do

Don’t write general, unclear button labels
Don’t write general, unclear button labels.
Don’t

Button alignment

In a Dialog, buttons are left aligned as it is considered a best practice, for the following reasons:

  • English text is read left to right and downwards, following an F-shaped pattern. Consequently, users often look towards the left edges as they scroll down;
  • Right-aligned buttons can be overlooked, especially on large screens or by users employing screen magnification;
  • Placing the most important button first reduces interaction cost for the majority of users.

Other best practices

Do use another label (e.g., “Not now”) if the main action is to cancel something.
Do use another label (e.g., “Not now”) if the main action is to cancel something.
Do

Don’t use “Cancel” as a label if the main action is to cancel something.
Don’t use “Cancel” as a label if the main action is to cancel something.
Don’t

Nesting components

A Dialog can use:

  • Icon component
  • Button component
  • Input component
  • Select component
  • Checkbox component
  • Radio button component
  • Text area component
  • Toast component

A Dialog can be used in:

  • Notifications

Resources