Modal

Use modals sparingly and for critical tasks that require completion or acknowledgment, rather than passive notices or information. Modals are designed to interrupt a user’s flow and tend to remove the user from an experience. When a modal is triggered, an overlay blocks the user from viewing the page’s content, keeping them from returning to the previous workflow until the task is completed or the user dismisses the modal.

Use only one modal at any given time. Do not place modals on top of existing modals or replace them with another modal without the user’s action.

Make sure to include clear steps that the user must take to dismiss or resolve the situation necessitating the use of the modal. Write instructive and clear text.

Button placement depends on the size of the modal. For extra-small (XS) and small (S) grids, the buttons should be justified at the bottom of the modal. For all other grid sizes, buttons should be right aligned. Follow the usage guidelines for primary and secondary buttons.

If the content exceeds the height of the modal container, a scrollbar will appear. However, try to avoid requiring users to scroll, since it decreases usability. Modal content should never scroll horizontally; if more space is required, use a larger modal.

A modal contains a transparent background overlay which partially obscures the content behind the modal. The overlay helps interrupt the on-page experience, so users can focus on the tasks outlined in the modal. The overlay should cover the page content and prevent the user from interacting with it until the action is complete or the modal is dismissed. While the overlay is a separate design element in the UI kit, the modal component incorporates the overlay in code. For more information on general overlay usage, visit the overlay page.

Follow recommended focus behavior for modal interactions
For people who rely on a keyboard or assistive technology and not a mouse to navigate, it’s important that focus control is placed before, during, and after the modal call-to-action as the component has been engineered for the design system. Refer to WAI-ARIA Authoring Practices for recommended modal focus behavior and expected keyboard interactions.
WCAG 2.1: 1.4.13 Content on Hover or Focus, 2.4.3 Focus Order, 2.1.1 Keyboard


Any modal not using a heading must still be labeled for accessibility
All modals require an accessible name, which is provided to users with assistive technology. Using a headline variant is strongly recommended, since it meets this requirement while providing the same experience for all users regardless of ability. If a modal has no headline, it should be labeled using aria-label or aria-labeled by.
WCAG 2.1: 1.3.1 Info and Relationships, 2.4.6 Headings and Labels


Modal must trap users’ focus until it is dismissed
When using a modal, a user should not be allowed to interact with any element on the page outside that modal dialog until they dismiss it, either with the close button or by initiating an action.
WCAG 2.1: 2.1.2 No Keyboard Trap, 2.1.1 Keyboard, 2.4.3 Focus Order

Body text
Modal content should be centered around task-oriented scenarios and what a user must do to complete that task. If the task is complicated or requires more than a few lines of instructional text, consider using another component or experience, such as a separate page in the workflow. If content exceeds the container height, an overflow scrollbar will appear, which may cause users to miss important context.


Capitalization
Use sentence case in headers and body text, unless referring to a proper noun. For buttons, use title case.


Modal headers
For modal headers, be brief and descriptive about the action a user must take to resolve the task. Try to use verb and noun combinations that clearly describe the dialog’s task or purpose. Header length should not exceed one line.


Punctuation
Do not punctuate button text or header text. For the modal body, use normal punctuation rules.