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.
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.
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.
Be sure to localize the
accessibilityModalLabel props, as well as any other text elements within Modal. Note that localization can lengthen text by 20 to 30 percent.
heading will render an H1 when a string is passed in and supports multiple alignment options with the
startaligned 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.
centeraligned text is the primary alignment for our Pinner products.
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.
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.
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.
Component quality checklist
Component is live in Figma, however may not be available for all platforms.
Component is available in code for web and mobile web.
Component is not currently available in code for iOS.
Component is not currently available in code for Android.
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 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.