View Storybook

A modal is an interstitial over page content that focuses the user’s attention exclusively on one task or piece of information.


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.

Use for

  • Confirming a destructive action that is about to happen
  • Entering the name and description of a new Call Center
  • Ask for a user’s consent for an action

Don't use for

  • Confirming an action took place (instead: use a Toast)
  • Revealing more information (instead: place content inline)
  • Displaying complex forms or large amounts of information (instead: place content inline)
  • 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.


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.
d-modal--animate-in .d-modal Adds transition styles for modal appearance.
d-modal--animate-out .d-modal Adds transition styles for modal exit.
d-modal__dialog--animate-in .d-modal__dialog Adds transition styles for modal dialog appearance.
d-modal__dialog--animate-out .d-modal__dialog Adds transition styles for modal dialog exit.


Base Style


Full Screen


Opened modals “trap focus,” meaning keyboard navigation controls are constrained to elements within the modal. Tabbing to the modal's last focusable element, and then pressing tab again would loop the focus back to the first element on the page. Focus doesn't return to the underlying page until the user explicitly dismisses the modal, in which case it would return to the place it was before the dialog opened.

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.

Focus should always begin on the first element within the dialog. This could be an OK button, or the first field in the form. An X button in the top right corner should be last in the tab order even though it may be visually above the other elements.

Check out the "Focus management" section of the following MDN Dialog document if you'd like to know more

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)