A Modal displays content that requires user interaction. Modals appear on a layer above the page and therefore block the content underneath, preventing users from interacting with anything else besides the Modal. The most common example of Modal is confirming an action the user has taken.

Props

Name
Type
Default
accessibilityModalLabel
Required
string
-

String that clients such as VoiceOver will read to describe the modal. Always localize the label. See Accessibility section for more info.

onDismiss
Required
() => void
-

Callback fired when Modal is dismissed by clicking on the backdrop outside of the Modal (if closeOnOutsideClick is true).

align
"start" | "center"
"center"

Specify the alignment of heading & subHeading strings. See the Heading variant for more info.

children
React.Node
-

Supply the element(s) that will be used as Modal's main content. See the Best Practices for more info.

closeOnOutsideClick
boolean
true

Close the modal when you click outside of it. See the outside click variant for more info.

React.Node
-

Supply the element(s) that will be used as Modal's custom footer. See the Best Practices for more info.

heading
React.Node
-

The text used for Modal's heading. See the Heading variant for more info.

role
"alertdialog" | "dialog"
"dialog"

The underlying ARIA role for the Modal. See the Accessibility Role section for more info.

size
"sm" | "md" | "lg" | number
"sm"

Determines the width of the Modal. See the size variant for more info.

sm: 540px | md: 720px | lg: 900px | number

subHeading
string
-

Subtext for Modal, only renders with heading strings. See the sub-heading variant for more info.

Usage guidelines

When to Use
  • Interrupting users to get confirmation on a user-triggered action.
  • Requesting minimal amounts of information from a user (1-2 fields only).
  • Capturing user's full attention for something important.
When Not to Use
  • Any time a separate, designated URL is desired.
  • Requesting large forms of information. Consider a Sheet or new page instead.
  • Any action that should not interrupt users from their current work stream.
  • On top of another modal, since this can create usability issues and confusion.

Best practices

Do

Use Modal when a response is required from the user. Clearly communicate what response is expected and make the action simple and straight forward, such as clicking a button to confirm. The most common responses will be related to confirming or canceling.

Do

Limit the number of actions in a Modal. A primary and secondary action should be used for Modals. The rarely used tertiary actions are often destructive, such as “Delete”.

Do

In the few cases where Modals are being used within the Pinner product, aim to prevent the content from needing to scroll at a reasonable screen size.

Don't

Use Modal for content that should have a dedicated surface, like login flows. Think about the core areas of your product that could appear in navigation. If a dedicated URL would be beneficial, use a full page instead. If the user interaction is an optional sub-task, consider using a Sheet.

Don't

Use Modal for long and complex tasks. Don’t keep the user in a Modal that takes multiple steps to exit. If multiple tasks are required, take the user to a separate page instead.

Don't

Add additional task-based Modals to the Pinner product. While these are currently used in some Pinner surfaces for editing, consider using a full page, Sheet, Flyout or inline editing for a better user experience.

Accessibility

Labels

We want to make sure Modals have a clear purpose when being read by a screen reader. accessibilityModalLabel allows us to update the spoken text for the heading prop and give it more context.

Edits made below will not be reflected in the example above, open the sandbox instead.

Role

Use the alertdialog role when the Modal requires the user’s immediate attention, such as an error or warning. For instance, navigating away from a page with active edits may trigger an alertdialog Modal that asks the user to confirm if they want to lose their changes. Learn more about the alertdialog role.

role="alertdialog"
Edits made below will not be reflected in the example above, open the sandbox instead.
role="dialog" (default)
Edits made below will not be reflected in the example above, open the sandbox instead.

Localization

Be sure to localize the heading, subheading and accessibilityModalLabel props, as well as any other text elements within Modal. Note that localization can lengthen text by 20 to 30 percent.

Variants

Heading

The heading will render an H1 when a string is passed in and supports multiple alignment options with the align prop.

  • Start
    start aligned text is the primary alignment for our Business products. It will be left-aligned in left-to-right languages and right-aligned in right-to-left languages.

  • Center
    center aligned text is the primary alignment for our Pinner products.

  • Custom
    If you need more control over the Modal heading, you can pass a custom React node as the heading prop and the Modal will render that instead. This feature should be used sparingly as most customization should be added to the content area. Please contact the Gestalt team if this is needed for your product.

Edits made below will not be reflected in the example above, open the sandbox instead.

Sub-heading

The subHeading is a container that can be used for subtext that provides additional context for the Modal. The sub-heading locks to the top under the heading.

Edits made below will not be reflected in the example above, open the sandbox instead.

Sizes

Modal has 3 size options: small (sm - 540px), medium (md - 720px) and large (lg - 900px). If absolutely necessary, a number representing a custom width can be provided instead, but we recommend using one of the standard sizes.
All Modals have a max-width of 100%.

Preventing close on outside click

By default, users can click outside the Modal (on the overlay) to close it. This can be disabled by setting closeOnOutsideClick to false. In most cases, the user should be prevented from closing the Modal if the action is required.

Sheet
To allow users to view optional information or complete sub-tasks in a workflow while keeping the context of the current page, use Sheet.

Toast
Toast provides temporary feedback on an interaction. Toasts appear at the bottom of a desktop screen or top of a mobile screen, instead of blocking the entire page.