Modal dialog contains a brief message and present at least one call to action that users must complete before the modal goes away. Since modal dialogs 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 modal dialogs 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 dialog. Don’t use a modal dialog just to let a user perform a task. Instead, use stacking trowsers or a drawer, depending on the context.

Appearance and behavior

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

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

  • The border radius for the modal dialog 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.

  • Modal dialogs appear using a fade in transition.

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

  • Content behind modal dialogs should not be scrollable.

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

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

  • Divider line appears for only for medium and large size modal dialogs

  • 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







Content guidelines for modal dialogs

Like page-level messages, most modal dialog 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 dialog 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 modal dialogs 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 modal dialogs with scrim (#000000 @40%)

  • Always have a focus on the modal dialog 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?