Modals
Modals focus the user’s attention exclusively on one task or piece of information via a window that sits on top of the page content.
Guidelines
Modals are used to present a short-term task the user needs to perform without losing the context of the underlying page. Users won't be able to interact with the page until they close the modal.
Although highly versatile, this doesn't mean modal dialogs are fit for all purposes. Modals are purposefully disruptive and should be used thoughtfully and sparingly, specifically in moments where focus is required or an action must be taken.
Don't use for | Use for |
---|---|
Confirming an action took place (instead: use a Toast) | Confirming a destructive action that is about to happen |
Revealing more information (instead: place content inline) | Entering the name and description of a new Call Center |
Displaying complex forms or large amounts of information (instead: place content inline) | Ask for a user’s consent for an action |
Displaying content unrelated to current task (instead: place content inline as link or banner) |
Best practices
- Limit the number of interactions in a modal. Remove anything that does not support the task.
- Avoid multiple steps that require navigation within the modal dialog.
- Avoid complex decision making that requires additional sources of information unavailable in the modal.
- Label links and buttons with a verb that indicates what happens when it’s selected.
- The primary button should reflect the modal title.
- Don’t surprise users by popping up a modal. Let a user’s action, such as a button click, trigger the modal. Uninvited modals may surprise the user and result in a quick dismissal of the window.
Classes
At minimum, modals contain a title and one button. They could also contain body text, brand illustrations, product wireframes, or multiple buttons.
Class | Applies to | Description |
---|---|---|
.d-modal | N/A | Parent modal container |
.d-modal__dialog | Child of .d-modal | Base dialog container for modal content. |
.d-modal__header | Child of .d-modal__dialog | Adds proper styling for the modal's header. |
.d-modal__content | Child of .d-modal__dialog | Adds proper styling for the modal's content area. |
.d-modal__footer | Child of .d-modal__dialog | Adds proper styling for the modal's footer. |
.d-modal__close | Child of .d-modal__dialog | Adds proper styling for the modal's dismiss button. |
.d-modal--full | .d-modal | Makes .d-modal__dialog take up as much of the screen as possible. |
.d-modal--danger | .d-modal | Adds styling for destructive actions. |
Accessibility
When opened modals “trap focus,” meaning keyboard navigation controls are constrained to elements within the modal. Focus doesn't return to the underlying page until the user explicitly dismisses the modal.
To ensure maximum compatibility, all a tags must have an hrefattribute. Also any elements which you don't want to be focusable (but might be focusable by default) must have their tabindex set to -1.
Attribute | Applies to | Description |
---|---|---|
aria-describedby=[id] | .d-modal | Provide the modal's copy ID here. Assistive technologies, such as screen readers, use this to associate text with a widget, elements groups, headings, definitions, etc. (Source) |
aria-hidden=[state] | .d-modal | Informs assistive technologies, such as screen readers, if they should ignore the element. This should not be confused with the HTML hidden attribute which tells the browser to not display an element. (Source) |
aria-label=[text] | .d-modal__close | Labels the close element for assistive technologies (Source) |
aria-labelledby=[id] | .d-modal | Supply the modal's title ID here. Assistive technologies, such as screen readers, use this attribute to catalog the document objects correctly. (Source) |
role="dialog" | .d-modal | Identifies the modal as a dialong element for assistive technologies (Source) |
role="document" | .d-modal__dialog | Helps assistive technologies to switch their reading mode from the larger document to a focused dialog window (Source) |
Examples
Default
<aside class="d-modal" id="modal-base" tabindex="-1" role="dialog" aria-labelledby="modal-title" aria-describedby="modal-description" aria-hidden="true">
<div class="d-modal__dialog" role="document">
<h1 class="d-modal__header" id="modal-title">…</h1>
<p class="d-modal__content" id="modal-description">…</p>
<footer class="d-modal__footer">
<button class="d-btn--primary" type="button">…</button>
<button class="d-btn" type="button">…</button>
</footer>
</div>
<a href="#" class="d-modal__close d-btn--circle" aria-label="Close"><IconClose \></a>
</aside>
Danger
A modal style for destructive or irreversible actions.
<aside class="d-modal d-modal--danger" id="modal-base" tabindex="-1" role="dialog" aria-labelledby="modal-title" aria-describedby="modal-description" aria-hidden="true">
<div class="d-modal__dialog" role="document">
<h1 class="d-modal__header" id="modal-title">…</h1>
<p class="d-modal__content" id="modal-description">…</p>
<footer class="d-modal__footer">
<button class="d-btn--danger--primary" type="button">…</button>
<button class="d-btn--danger" type="button">…</button>
</footer>
</div>
<a href="#" class="d-modal__close d-btn--circle" aria-label="Close"><IconClose \></a>
</aside>
With Inline Banner
Since modals are a small form factor, our inline banners are anchored to the top of the modal to save space.
<aside class="d-modal" id="modal-base" tabindex="-1" role="dialog" aria-labelledby="modal-title" aria-describedby="modal-description" aria-hidden="true">
<div class="d-modal__banner d-d-none js-example-modal-banner-full">…</div>
<div class="d-modal__dialog" role="document">
<h1 class="d-modal__header" id="modal-title">…</h1>
<p class="d-modal__content" id="modal-description">…</p>
<footer class="d-modal__footer">
<button class="d-btn--primary" type="button">…</button>
<button class="d-btn" type="button">…</button>
</footer>
</div>
<a href="#" class="d-modal__close d-btn--circle" aria-label="Close"><IconClose \></a>
</aside>