Modal

Anatomy

Guidelines

Modals are dialog boxes that display over the main page content that require the user's attention. Modals may hold supplemental information, request user interaction, or include a related workflow.

When to use

Be decisive when using Modals—versatility paves the road to misuse. Consider the following use cases before deciding to use a Modal:

• Action confirmation. Performing destructive actions such as deleting data should require additional input from the user.
• Additional tasks. Some required tasks may be too large to fit within the workflow or not large or contextually different enough to warrant its own page. Modals fit this use case.
• Feature moments. Modals can be used to celebrate user actions and accomplishments such as starting a new campaign or exporting data. Use these sparingly.

Modal vs Drawer and Popover

Modals, Drawers, and Popovers are all dialogs that overlay page content to divert the user's attention. However, it's important to understand the difference as they are not interchangeable:

• Modals are centered in the viewport and render page content inert. They're useful when users must confirm a task, such as short forms, agreements, and confirmations.
• Drawers slide in from the edge of the viewport and may allow some interaction with the page content. Use them for content that has less contextual meaning to the main page such as updating settings or full-detail views without leaving the page.
• Popovers anchor to their trigger element and appear inline without blocking a large portion of the page. They're more suited for smaller snippets of supplementary material or quickly dismissable interactions.

Best practices

Nesting

Never nest Modals. While doing so is possible, it's not a pattern we'd like to encourage due to poor user experience. Nested Modals complicate a workflow and increase the cognitive load a user may experience when attempting to complete a single, focused task.

Consider the following questions if nested Modals become a consideration:

• Can the flow be reworked?
• Can the content be written inline or on another page?
• Can another component such as a Popover be used?

Common patterns

Though Modals are highly customizable to fit a variety of use cases, it's best to reach for existing Modal patterns to maintain consistency throughout the system and application. Decide if your use case fits one of the following patterns before creating a new standard.

Types

Appearance

Close button

The close button is visible by default for an easily visible way to dismiss the Modal. If required, it may be hidden. Hiding the close button are more appropriate for Modals that require immediate user input for an important action, such as deleting data. For such use cases, be sure to include a "Cancel" button.

Inset

ModalInset renders content edge-to-edge within the modal, extending over the default padding. Use it for full-width backgrounds, images, or dividers that should bleed to the modal's edges.

Sizes

Behaviors

Animation

Modals animate in and out with a fade and downward slide. The overlay fades in and out independently. The default animation duration is 125ms but can be customized.

Scrolling

By default, when Modal content exceeds the Modal container's max height, body content will scroll while the header and footer remain fixed. Scroll behavior can be changed so the entire Modal will scroll with the viewport instead.

Dismissal

Modals can be dismissed through multiple methods: close button, action button, overlay click, and the Escape key. The close button may be hidden and both the Escape key and overlay click may be disabled with props.

Use non-dismissable Modals for cases where user interaction is mandatory, such as confirming a destructive action.

Note: Non-dismissable Modal examples are dismissable with the Escape key. This is purely for display purposes.

Content

When writing Modal content, keep the patterns below in mind:

Structure

table

Element	Pattern	Example
Title	Action + object name?	Delete Q3 Re-engagement?
Body	Consequence. State if irreversible or recovery window.	This campaign will be deleted. This cannot be undone.
Confirm	Verb + object	Delete campaign
Cancel	Cancel	Cancel

Action labels

Footer action labels should describe what action will take place when activated. Mirror the title's verb when possible to reinforce the action.

Content length

While Modals are capable of expecting longer content than Popovers, we recommend keeping its content as concise as possible. The goal of a Modal is to help complete a single focused task. If more attention is required or multi-step tasks or workflows are intended, consider moving the content to a new page.

Titles

Titles should clearly describe the purpose of the modal in sentence case and include the object's name. When asking for confirmation, be sure the title ends in a question mark.