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>