Modals
Search the component library

Modals

v2.0.6

Modals display content that temporarily blocks interactions with the main view of the UI. Use modals sparingly to avoid unnecessarily interrupting the users workflow.

Note: Modals can be particularly frustrating to users with screen readers because they will lose their place in the application. 

Usage

Use a modal for these type of messages:

  • Confirming or making decisions (see example below).
  • Providing additional information.
  • Completing important tasks in a workflow.
  • Asking for feedback; e.g., "How would you rate this tutorial?"
Standard modal

Modals versus alerts

It’s easy to confuse modals with alerts. Modals interrupt the users' workflow by temporarily blocking the current view while alerts coexist on the page and don't interfere with the users' workflow. Don’t use a modal when an alert is more appropriate.

Components

There are three parts to a modal:

  • Header (Optional)

    Users should be able to understand their choices based on the header and the button label. If you use a header, be sure the question or statement is clear and followed by an explanation in the content area. 

    Note: Even if you don't use a header, you still must provide the developer with a name for the modal. Screen reader users will need a name for accessibility reasons. 

  • Content

  • Actions (Optional)

    Note: If you don't include any actions, then be sure to include an X close button to dismiss the modal. This is an accessibility requirement.

Modal header
Modal actions

Behavior

Dismissing

Modal with actions

If a modal requires users to take an action, then you should force them to make a decision by clicking a button. Don’t include an X close button or allow users to click outside the modal to dismiss it.

Modal without actions

If a modal doesn't require users to take an action and the content isn't critical, then you don’t need to use buttons. Users can simply click an X close button or anywhere outside the modal to close it. For example, a modal that displays additional information about an instructor helping students choose a class, doesn’t require buttons.

Modal with actions

Modal without actions

Scrolling

When the content exceeds the height of the viewport, the modal becomes scrollable. The scrolling behavior differs depending on the scenarios.

Modal with actions

By default, the buttons will "stick" to the bottom of the viewport making sure that they are visible to the users upfront. Users scroll inside the modal to access more content. However, if it provides a better user experience with page scroll (scrolling the whole page) in your use case, you could do so by letting the developers know.

Note: The modal will default to page scroll when the vertical space is insufficient (under 400px) even if there are buttons. This is to support users who may have to zoom in significantly.

Modal without actions

In this case, the modal will extend “below the fold” so that users know there is more content to scroll through. This is called “page scroll” as opposed to the in-modal scroll.

Modal with actions (Mobile). This prototype failed to show the scroll bar due to technical limitation, but the actual build should have the scroll bar visible at all times for this modal.

Modal without actions (Mobile)

Design guidelines

Don't allow modals to launch modals

Launching a modal within a modal adds complexity and confuses users. Find alternative solutions such as creating a separate page for the task.

Avoid long content

Modals are not designed for displaying long content, especially when we want the users to actually read the content. Consider in-line expansion within the originating page or displaying the information on a separate page for a better user experience.

Avoid nested scrolling

On narrow devices, there isn't enough horizontal room for a scrolling area inside a modal if the modal exceeds the viewport. Using nested scrolling can become a usability issue.

Button placement

See buttons for how to place the buttons. Avoid having more than two buttons in a modal to keep it simple for users.

Responsive behavior

The modal adjusts itself on different devices to optimize the user experience. The modal becomes narrower and have a more compact layout on smaller devices. For more details, see the redlines.

For native mobile apps, use the native modal. The guideline in this documentation is for responsive web mobile design.

Modal on desktop (Viewport >= 768px)

Modal with actions

Redlines

Responsive behavior

The layout of the modal changes at different breakpoints:

  • Medium device (md) and up (768px <= viewport)
  • Small device (sm) (480px <= viewport < 768px)
  • Extra small device (xs) (320px <= viewport < 480px)
Widthmd and up: 600px
sm: 440px
xs: Auto
Margin (distance between the modal and the window)Minimum: 20px
Spacingmd devices have a more generous spacing (see illustration on the right)
sm and xs devices have a more compact layout (see illustration on the left)
Header textmd: Large Section UI Heading 24px
sm and xs: Basic Section UI Heading 20px
Charcoal
Content textBasic Body Copy 14px
Charcoal
Border radius2px
ButtonPrimary Buttons (Large)
"X" iconSize: remove-sm-24
Touch target: 44x44px
Medium Gray
OverlayCharcoal
Opacity: 60%
Focus behaviorModals retain focus, including keyboard focus, until a certain action has been taken.
Follow the default behaviors for "X" defined in the drawer
Follow the default behaviors for buttons

Use the native modal for native mobile apps. The specs in this documentation is for responsive web mobile design.

Scrolling modals

When the content exceeds the height of the viewport, the modal will become scrollable. The scrolling behavior differs depending on the scenarios:

  • Modal with actions: Sticky buttons (with exceptions specified below under "responsive behavior")
  • Modal without actions: Page scroll
Scroll barDefault scroll bar by browser
If possible, make the scroll bar visible even when user is not scrolling
LineThickness: 1px
Concrete
Focus behaviorFor sticky buttons, the scrollable area must be focusable and scrollable via the keyboard
Responsive behaviorThe sticky header/footer should be disabled and a standard page scroll used if the viewport height is 400px or less

Modal with buttons

Modal without buttons (Desktop)

Modal without buttons (Mobile)

Buttons are responsive

  • md and up: Default (fixed padding)
  • sm & xs: Expanded (filling up the full width of the container)

Buttons stack up when they don’t fit

Button labels should be as concise as possible - one or two words. However, in the case where multiple buttons just can’t fit in one row on a narrow device, they will stack up by default.

Changelog

2.0.6

  • ADDED: Clarification around scrolling configuration

2.0.5

  • REFINED: Content to make it more clear and concise
  • CHANGED: The minimum margin on the top and bottom of the modal to be 20px
  • FIXED: Broken links

2.0.4

  • FIXED: Scrolling behavior of modal actions on a vertically constrained or zoomed in screen
  • CHANGED: Organization of usage guidelines

2.0.3

  • UPDATED: UI copy in the example images
  • ADDED: Link to redlines per feature
  • UPDATED: The button style in the video example

2.0.2

  • UPDATED: Dependencies (version number and links)
  • UPDATED: Images showing mockups at mobile size to have a gray (#f5f5f5) background color

2.0.1

  • CHANGED: Button style to match Buttons v2.2.1 (Blue buttons)
  • CHANGED: Touch target for the "X" icon from 36x36px to 44x44px to meet accessibility standard
  • CHANGED: Margin from auto to specific values (60/20/20 for different breakpoints)
  • UPDATED: Button placement by moving the default button "Cancel" from the far left of the modal to the right. Note that it is still on the left relatively to the primary button.

2.0.0

  • Re-skinned with the latest styles
  • ADDED: Sticky buttons for long content

1.0.1

  • FIXED: Responsive image button bar and sizing.

1.0.0

Initial version