Design pattern - Modals
Problem
- We have the new content format in a modal after the first version of the modal guide was created. (e.g. https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6808)
- So we might need to iterate the document along with the product evolution.
Solution
Iterate and add modals to our pattern library and design system.
Example(s)
Usage
Modals are used when you need a user response, to reveal critical information or to show info without losing the overall context of the page. Use modals sparingly because they interrupt user workflow. When designing an experience that incorporates the need for a modal consider one of the following before reverting to a modal:
- Inline content: Present your content inline to avoid disruption to the user's flow.
- Expanding elements: Utilize elements such as accordions, tooltips or other non-modal patterns to convey your information.
- New page: take the user to a different page so that the interaction may be isolated without losing access to core navigational elements within the application.
Note: Modals should be considered the second best option when designing an experience.
Sizes
There are 4 sizes for modals:
Small - 512px
|
---|
![]() |
Medium - 768px
|
![]() |
Large/max-width - 990px
|
![]() |
Mobile - viewport width
|
![]() |
Types
Informational Modal |
---|
For use when there is a need to display information or instruction to a user that is critical to their task. |
![]() |
Confirmation Modal |
---|
For use when you require the user to reaffirm a decision or action the took on the page, typically a yes or no response. |
![]() |
Input Modal |
---|
For use when the user needs to interact with the application. These may include but are not limited to forms, dropdowns, selectors, file uploaders. |
![]() |
Elements
There are three main elements of a modal.
-
Header: The header is either a question, descriptive phrase or title. The header also contains the close icon in every instance. The title uses the h3 style.
-
Body: The content in the body should never be ambiguous and unclear. It provides specific information.
- Content style: Content should conform to our design guidelines, there is no default style for certain elements within modals.
- References to commits, branches, and tags should be monospaced.
-
Actions: Should contain no more than 3 actions and no fewer than 1 and should always be place within an action bar at the bottom of the modal.
- Dismissive actions are always left aligned and affirmative actions are always right aligned.
- In cases where there are 2 affirmative actions the order should be, from left to right, secondary action -> primary action
- There will be some cases where there are no designated primary and secondary actions. In this case, use the secondary button style for all buttons.
- There will be some cases where no actions are designated for the modal. In these cases, an action bar should be used with a dismissive action. There should always be two ways to close/dismiss a modal, this is important to remember because some modals can be tall and we want to avoid making the user scroll to close a modal.
- Dismissive actions are always left aligned and affirmative actions are always right aligned.
Behavior
Autofocus The first focusable item should be auto-focused within the modal dialog so that the user can't tab in the modal and not get suck behind the overlay. This behavior follows accessibility guidelines for modals: https://www.w3.org/TR/wai-aria-practices/examples/dialog-modal/dialog.html
Scrolling
The height of the modal is determined by the content. Some users have smaller screens, so for these instances where the content requires scrolling, it's best practice to extend the height of the modal below the window to avoid double scrolling.
Dos and dont's
|
|
---|---|
• Pin the modal 60px below the top of the window | • Center the modal vertically in the window |
• Align buttons with dismissive actions on the left and buttons with affirmative actions on the right | • Group buttons or align all buttons to the right. |
Related patterns
- Alerts
- Toasts
Links / references
https://modalzmodalzmodalz.com/
Pattern checklist
Make sure these are completed before closing the issue, with a link to the relevant commit, if applicable.
-
Ensure that you have broken things down into atoms, molecules, and organisms. -
Check that you have not created a duplicate of an existing pattern. -
Ensure that you have used the proper method for creating the pattern depending on the complexity. Atoms and molecules are symbols, organisms are groups. -
Make sure that typography is using text styles. When applicable used shared styles for colors. -
QA check by another UXer -
Add changes to the pattern library -
Create an issue to add the pattern documentation to the Design System. Mark it as related to this issue. -
Add an agenda item to the next UX weekly call to inform everyone (if new pattern, not yet used in the application)