View in Storybook
Anatomy
All modals contain by default a Header, Body (using our base Container) and Footer components. Additionally, Tabs are also available in all modals should a consumer require them.
- Header: Contains the modal title. This will contain the most important information about a modal's content. Optional elements that can be displayed here are icons and badges.
- Subtext (optional): Accompanying copy to support the title of the modal.
- Tabs (optional): To display sections of content within the same modal. Tabs should always be left-aligned when shown.
- Body: Expands on the information in the header and gives more details about the modal action.
- Footer: Contains a primary and optional secondary action.
Types
Modal
The primary modal is made up of header, body, and footer. The body content can be customized depending on the purpose of the modal. The action buttons in every modal should always be right-aligned.
Dialog
These are used to provide critical information or prompt action. The action buttons in every dialog should always be filled.
Usage
This section includes guidelines for designers and developers about the usage of this component in different contexts.
|
Passive
Primary modals are used to complete one task at a time. They can contain static elements such as body texts, headings, tabs and media. Choose the appropriate size to avoid poor readability.
|
|---|
|
Confirmation
Use confirmation dialogs when you either need the user's input or confirmation or when you need them to acknowledge important information. |
|---|
|
Title as the message
When the message in a modal dialog is short, don't use the helper text to avoid being redundant. |
|---|
Best practice
Use modals when you need people to focus on a specific piece of information, or decision, or task. Modals are meant to be disruptive, so make sure you use them sparingly.
- Modals should focus on a specific task, as opposed to complex multiple steps, and the task should begin and end within the modal itself. Completing the task should take people back to the screen they were on before.
- Use a modal dialog to confirm a decision made by the user. Clearly describe the action and its potential outcomes, and make sure the title and the button focus on reinforcing the action with consistent wording.
Content padding
|
Separators
Consumers can toggle on 1px separators on either the Headers and/or Footers within modals. These are useful when additional space is needed between content. When a modal has limited content, only 1 of these separtors should be toggled on. We recommend the Footer separator in these instances. |
|---|
|
Matching
We are consistent with the padding that is already used in the modal a consumer has selected. For example the Small modal variant by default uses 20px paddings. This should therefore be used around the Body content inside the modal.
|
|---|
|
Consistancy
When using multiple horizontal and vertical slots in more complex modals, be consistent in the paddings between them. We recommend using 16px between slots but there maybe instances where smaller or larger paddings are required. Always think in multiples of 4px. More information on this can be found on the Spacing guidelines. |
|---|
Do's and Don'ts
|
Do |
Don't |
|---|---|
|
✅ Use for confirmations and conditional changes. |
🚫 Use for nonessential information that is not related to the current userflow. |
|
✅ Use when the user is required to take an action. |
🚫 Use when the modal requires additional information for decision making that is unavailable in the modal itself. |
|
✅ Use when you need to display content that temporarily blocks interactions with the main view of an application. |
🚫 Open a modal window on top of another modal. |
|
✅ Use when you need to ask a confirmation from a user before proceeding. |
|
|
✅ Use for important warnings, as a way to prevent or correct critical errors. |
|
Sizes
Two sizes are available for dialogs (tiny and small), and three sizes for modals (small, default, and large). Choose based on the space your content requires. Modals with short messages should use a dialog or a small-sized modal.
Max width
Modals and dialogs come in various sizes. These set the maximum width a modal can have on large screens.
|
Size |
Max-width |
Type |
|---|---|---|
|
Tiny |
320px |
Dialog |
|
Small |
480px |
Dialog and Modal |
|
Default |
640px |
Modal |
|
Large |
800px |
Modal |
Max height
Each primary modal has a max height set, to maintain an appropriate window ratio. If the max height causes too much scrolling on your modal, consider going for a bigger size. If you're using the large modal already, this may be a sign that you need a full page.
|
Size |
Viewpoint height |
|---|---|
|
Small |
70vh |
|
Medium |
80vh |
|
Large |
90vh |
Scrolling behavior
When the body content is longer than the modal height, the body section should scroll vertically. Headers and footers should be fixed. The body content should not scroll horizontally; use a larger size modal instead.
Placement
Our modals and dialogs, no matter what size, are always positioned centre-aligned and this position is responsive to changes in screen dimensions. To enhance user focus further, a backdrop overlay is placed on top of the page content beneath. Information on how to use this correctly can be found in our core component library.
Tutorial
This instructional video explains how to use our slots in components correctly when working with Modal or Dialog. As this component has many variations, the slots demonstrate how flexible they are and how consumers can still be creative within our fixed container constraints.