Modals contain a brief message and present at least one call to action that users must complete before the modal goes away. Since modals stop users from continuing, these messages are usually more important than the ones we display in page-level warnings or alerts.


Except for special cases, such as in-flow sign-up steps, we mainly use modals for messaging:

  • For sign-in and sign-up flows

  • To introduce users to how things work, especially for first-time use

  • To display important information users need to respond to. This is especially useful in cases when we need to make sure users want to take an action (such as deleting information) and when users need to make a decision or complete an important task at a specific time in their workflow.

  • To help users focus on an article, video, or image

  • For persistent alert messaging, such as when we want to remind users to complete an important action outside of their current workflow. Example: The user needs to update how often they file or make payments.

We usually try to limit the number of interactions in a modal. Don’t use a modal just to let a user perform a task. Instead, use stacking trowsers or a drawer, depending on the context.

Appearance and behavior

  • Modals come in three widths: 384, 576, and 752 pixels.

  • The background behind the modal is grayed out (40% opacity, black).

  • The border radius for the modal is 8 pixels.

  • If there is one call to action button, center it.

  • If there are primary and secondary calls to action, the primary call is always on the right, secondary on the left.

  • Modals appear using a fade in transition.

  • Modals should not be scrollable. We make an exception for when content is hidden behind the mobile softkeys. The modal component scrolls, but not the content inside.

  • Content behind modals should not be scrollable.

  • Don’t use controls such as checkboxes or dropdowns in 384-px modals.

  • Use the full-screen experience for modal typeahead in mobile.

  • Divider line appears for only for medium and large size modals

  • Minimum dialog height is192px

  • Maximum dialog height is 680px


One button Modal dialog



Two button Modal dialog




Three button Modal dialog


Image usage

Designers will need to use their judgment when using images. Here is some guidance to get you started:

  • Define when icons are used

  • Define when illustrations are used, full width header vs. full bleed

  • Avoid using photography







Mobile usage

Coming soon!

Content guidelines for modals

Like page-level messages, most modal messages consist of three elements: the information or alert, additional details if needed, and a call (or calls) to action. Depending on the pattern you use, the modal might also begin with a title.

  1. Title (optional):

    The title briefly introduces the information. Keep it succinct and simple, like “Connect your bank” or “Check your payment.”

  2. Information or alert:

    Tell users what’s going on or show the information they need to see. Be honest and let users know what the system did, what they did, or what they’re about to do.

  3. More information (optional):

    If we have information that helps users understand what’s happening or why, we can include an additional sentence. We usually want to keep modals brief, so more information is optional.

  4. Call to action:

    The call to action lets users know what to do next. Keep these buttons brief and direct.


  • Align header and content sections to the left

  • Include a close icon control when an explicit dismissive action is not present in the CTA section

  • Labels should be clear and coordinate with content.

  • Do remove the  close icon control when a dismissive action is included in the CTA section.

  • Always use modals with scrim (#000000 @40%)

  • Always have a focus on the modal when modal when it appears

  • Always include a dismiss action and make it discoverable.



  • Display the close icon control when a dismissive action is included with the CTA section

  • Don’t include any text in the CTA section. Content should be clear as to what is being asked and the action. Labels should be clear and coordinate with content.

  • Don’t wrap the primary and secondary button when the horizontal space is between secondary and tertiary button is greater than 40px


  • Was this Helpful?