A Dialog is displayed on top of the page content, focusing the user’s attention on one task or piece of information.
Forms in Dialogs
Forms often appear in Dialogs. See Forms in Overlays for guidance on the key decisions you'll need to make when building forms in overlays, including how to format your forms and choosing the overlay size that best fits your content.
Anatomy
Anatomy summary lists and describes all the elements within a component (including nested components).
|
Element |
Description |
Optional? |
|---|---|---|
|
1. Container |
Dialog container that sits on top of page content. |
No |
|
2. Title |
Mandatory title (maximum 5 words) that describes the dialog’s purpose. |
No |
|
3. Dismiss button |
Closes the dialog. |
See Best Practices in Usage. |
|
4. Divider |
Separates the header from the main content. |
No |
|
5. Leading icon |
Precedes a subtitle to call out a warning or danger message. |
Yes |
|
6. Subtitle |
Introduces a sub-section of content. |
Yes |
|
7. Description |
Description to provide information, including optional inline links. |
Yes |
|
8. Body |
Main content area that allows for multiple types of content. |
No |
|
9. Footer - Actions |
Action(s) that the user can take, such as to cancel, confirm, create, edit, or upload. |
No |
|
10. Side panel |
Container to display additional information. |
Yes |
|
11. Illustration |
Infographic that is informative on its own, or an image that supports an accompanying description. |
Yes |
|
12. Collapse button |
Closes the side panel. |
Not optional when side panel exists. |
|
13. Subtitle |
Introduces the side panel content. |
Yes |
|
14. Description |
Description to provide additional information, including optional inline links. |
Yes |
|
15. Footer - Back button |
Action that the user can take to go “back” in a multi-step flow. |
Yes |
|
16. Footer - StepCount |
Used in a multi-step flow to indicate current step out of [x] number of steps. |
Yes |
|
17. Expand button |
Opens the side panel. |
Not optional when side panel exists. |
Header
The header contains a mandatory title and may include a dismiss button depending on the type of Dialog.
Do not use a dismiss button for confirmation dialogs, including destructive actions such as “Unsaved changes” and “Delete”. For more details, see Best Practices in Usage.
A title should be concise with only a few words. Avoid writing a title that wraps over two lines.
In Figma the title copy is pre-defined for the following Dialog types (this isn’t enforced in code, so make sure it’s implemented correctly):
- Unsaved changes
- Danger
Body
The body is the main content area that allows for multiple types of content, e.g., description, form fields, buttons.
In Figma, description copy is pre-defined for the following Dialog types (this isn’t enforced in code, so make sure it’s implemented correctly):
- Unsaved changes
- Danger
- Empty
Expanded side panel
Dialogs have an optional, collapsible side panel to display supporting imagery and/or text.
Footer
The footer contains the actions that the user can take. Several variants are available to cater to different Dialog types.
In Figma, all button copy is pre-defined. If you require an option that doesn’t exist, please follow our Contribution guidelines. However this is not enforced in code, so make sure it’s implemented correctly when it comes to build stage.
|
Element |
Description |
Example |
|---|---|---|
|
1. Delete |
Uses a destructive button to indicate that the user is about to delete something |
Use when deleting an entity, such as an environment or project |
|
2. Unsaved changes |
Used only for the “Unsaved changes” Dialog |
N/A |
|
3. Cancel + Primary action |
Generic button combination suitable for most Dialogs |
“Ok, got it”, Update, Add, Select, Save, Import, Upload |
Variants
Variants contain different versions of the component depending on specific properties, such as state, size, colour, optional iconography, etc.
| Property | Values | Default |
|---|---|---|
| size Variant | small | medium | large | extraLarge | small |
| type Variant | default | unsaved changes | delete entity | no entities | default |
| hasSteps Variant | false | true | false |
| ↳ hasInput Variant | false | true | false |
| isDestructive Variant | false | true | false |
| showHideSidePanel Variant | false | true | false |
Size
There are four sizes available:
- small (480px)
- medium (600px)
- large (800px)
- extraLarge (1000px)
Dialogs with minimal content are better suited to a small width. Larger widths (medium, large, and extraLarge) are best for content that needs extra breathing space to improve legibility and usability, e.g., form fields with long labels and/or inputs, File Upload, Cards, or a Progress Tracker.
Figma-Only Types
Template
A basic template to add your own title, description, and any other components required for your Dialog.
Please check whether a suitable pre-defined Dialog type is available before using this template.
Unsaved changes
This pre-defined Dialog is triggered when a user has clicked somewhere that will take them away from the current page which has unsaved changes. It gives the user two choices:
- Leave the page and discard any unsaved changes; or
- Stay on the page to continue editing (and take the opportunity to save their changes, if they wish to do so).
Delete
Moderate danger level
This pre-defined Dialog is triggered when a user clicks a “Delete” button. It warns the user that this action is permanent and helps to prevent critical user error.
_ENTITY_ should be replaced with the appropriate entity, such as tenant or environment.
High danger level
This pre-defined Dialog is triggered when a user clicks a “Delete” button to delete a critical entity, such as a project. It adds further friction by including an input field to prevent critical user error.
_CUSTOM NAME_ should be replaced with the user’s custom project name.
Empty
This pre-defined Dialog is triggered when a user wants to undertake a task, but that task depends on having at least one of a specific entity. The Dialog prompts the user to add that entity.
_ENTITY_ should be replaced with the appropriate entity, such as tenant or environment.
_PAGE_ should be replaced with the name of the page that the user will be directed to, to add the entity. It is the same URL used for the Add _ENTITY_ button.
Behaviour
Closing the dialog
In addition to the dismiss and “Cancel” buttons, users can close a Dialog by tapping the esc key or by clicking anywhere outside the Dialog.
The ability to close the Dialog by clicking outside of it depends on the showDismissButton property.
Dialogs with a side panel do not have a dismiss button.
Side panel
The side panel opens and closes with a growing and shrinking animation.
The side panel closes when the user presses the collapse (chevrons) button. They can open it again by pressing the expand button (chevrons face the other direction to indicate opening).
Component dependencies
This component is internally dependent on the following components:
Icons
Our icon library with guidelines on using and adding icons
Button
Buttons allow users to take actions that will trigger a response.
Related components
Recommended reading
Other documentation that will help guide your thinking when working with this component.
Help and support