Modals

A modal is a user-initiated layer featuring a short-term task. The modal disables the rest of the interface, is always dismissible, and comes with optional actions.

Modal Taxonomy


Usage

The modal will always be a sub-task of the larger feature being used. Once the action within a modal is complete, the user can get back to the main job.

Always user-initiated. A modal shouldn’t appear without a user taking action, and should always provide context explaining what the modal does.

Always dismissible. Because the modal is user-initiated, they should have the option to dismiss at anytime. Every modal can be dismissed by one of 3-4 ways: Dismiss (required), pressing ESC key, clicking the scrim or Cancel (optional).

Always a sub-task. The modal is a blocking task. The user must take action, either in completing the sub-task or dismissing the window, to return to the main interface.

Never one of many steps. The user will open a modal with one action in mind. We don’t want to move the main job into this modal. Allow them to complete the single sub-task and choose a next step for themselves.

Never allow more than one to be open at once. One modal should never open another. The sub-task should either be completed or dismissed before the user can take any other action that could potentially open another modal.


Elevation

Modals sit near the top of our stacking context (only system status and alerts are higher), ensuring they properly layer above the rest of the interface. The use of Elevation Shadow 3 visually reinforces that layered separation.

This elevation does not affect environment levels within the modal. You should still start with Level 0, increasing one level at a time. The shadow will distinguish the modal from the rest of the page

Modal Stack Order

Sizes

Modals have two size options: default and large. The two differ only in width not height—the latter varies depending on how much content appears in the modal.

Regardless of which size you choose, a modal should never extend beyond the boundaries of the screen.

Default applies to the majority of our modals. Use it with one column of content, scrollable or non-scrollable.

Modal Default

Use large for modals requiring two columns of content (but make sure that content can gracefully shrink to one column on mobile).

Modal Large

The whole modal, whether default or large, should have a padding of 1rem.

Modal Spacing


Titles

The modal title (located in the Header) should always be a Level 3 Heading. Sticking to our Microcopy Guidelines, it should use title case and prioritize keywords.

Call out the action they’re taking by performing this sub-task.

Make sure it’s congruent with the button’s call-to-action.

Avoid making the title a question. This isn’t a “never”, but should be done sparingly.


Content

A modal’s content is typically one of two types: plain text or a checklist/form field.

Use plain text to confirm an action initiated by the user. Their only interaction with the modal will occur in the footer (Primary Action, Secondary Action or Cancel).

Modal Content Default

Use a checklist or form field to help the user add, remove or customize items. The checklist would provide a list of existing options while a form field allows them to enter new details.

Anytime a checklist or form field is involved, the Primary Action should be disabled until the user interacts with the content.

Modal Content Large

Regardless of layout, we recommend the content be concise and not scroll. However, scrolling is allowed when necessary. In those cases, the content should be set between a fixed Header and Footer. Use shadows to indicate additional content is available in either direction.

Modal Scroll Shadow

Check our Microcopy Guidelines for tips on capitalization, punctuation and parallel structure within the modal.


Buttons

The default size for all modal buttons is medium, though some occasions call for small—never large.

Calls-to-action and other button microcopy should reflect what appears in the modal title. Be sure to repeat the verb explaining the purpose of the modal. For more info on title-to-CTA congruence, check our guidelines.

Each modal can have up to three buttons: Primary Action, Secondary Action and Cancel.

Modal Actions

The Primary Action is required on every modal. Confirm whatever sub-task the user initiated.

The Secondary Action is optional. Use it to cancel the modal (phrased to counteract the Primary Action) or perform a different task altogether (not necessarily opposite the Primary Action).

You can also use a Minimal Secondary Cancel either in place of the Secondary Action or alongside both Primary and Secondary, assuming the Secondary does not cancel the modal.

All buttons are located in the Footer. The Primary Action is right-aligned with the Secondary Action and/or Cancel one half-space to the left.