UX Framework
Modal
Search the component library

Modal

v2.0.6
Download UI Kit v1.9.0 Code

Modal interrupts the user with a message or request for certain actions with a block of content on top of the main view.

Download UI Kit v1.9.0 Code

Dependencies

Buttons v2.2.1

Typography v2.1.1

Colors v3.0.1

Icons v2.3.0

Breakpoints v1.0.2

Documents

UX Accessibility Checklist

Documentation Assets (Sketch)

Usage

Use modals when it is necessary to interrupt users with a message or request for certain actions. For example:

  • Confirming decisions E.g., “Are you sure?” moment.
  • Providing additional information
  • Asking for a decision or complete a task at an important part of their workflow.
  • Asking for feedback E.g., “How would you rate this tutorial?”

Use them sparingly as they are interruptive. Modals can be particularly frustrating for screen reader users because these users will lose their place in the application.

Basic Modal

Modals vs. alerts

It’s easy to confuse alerts with modals. Modals interrupt users by blocking the current view while alerts coexist on the page and do not stop the user flow. Don’t use modals when alerts are more appropriate as modals are intrusive.

Components

Modals contains three parts:

  • Header (Optional)

    Users should be able to understand the choices based on the header and button label. If header is applied, make the question or statement clear followed by an explanation in the content area. Avoid apologies or ambiguity such as “Be careful!” or “Are you sure?”.

    Note that when there is no header, designer should still provide a name for the modal to the developers because a screen reader user would need this for accessibility reasons.

  • Content

  • Actions (Optional)

    When there’s no actions, you must include the “X” as a way to dismiss the modals to meet accessibility requirements.

Modal Header
Modal Actions

Behavior

Dismissing the modal

Here are two different approaches:

  • Modals with actions

    When an action is required from users, force them to make a decision by clicking a button. Don’t include the “X” or allow the users to click outside the modal to dismiss it.

  • Modals without actions

    If the modal content is not as critical to the users, then you don’t need buttons. Users can simply click the “X” or anywhere outside the modal to close it. For example, a modal that displays additional information about an instructor to help students choose a class doesn’t need buttons.

Modal with actions

Modal without actions

Scrolling

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

  • Modals 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 that 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 launching modals

Launching a modal within a modal adds complexity and confusion for the users. Look for 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 scroll within a modal

On narrow devices, there isn’t enough horizontal room for a scrolling area inside modal if the modal happens to exceed the viewport as well. This would 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 on iPhone 5 (Viewport = 320dp)

Redlines

Responsive behavior

They 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)
Width
  • md and up: 600px
  • sm: 440px
  • xs: Auto
Margin (Distance between the modal and the window)
  • Minimum: 20px
Spacing
  • md 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 text
Content text
Border Radius
  • 2px
Button
“X” icon
Overlay
Focus behavior

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 Bar
  • Default scroll bar by browser
  • If possible, make the scroll bar visible even when user is not scrolling
Line
Focus Behavior
  • For sticky buttons, the scrollable area must be focusable and scrollable via the keyboard
Responsive Behavior
  • The 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

Linda Tsai

  • ADDED: Clarification around scrolling configuration

2.0.5

Linda Tsai

  • 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