Modal

The modal component displays important content or actions by overlaying it on the page, ensuring the user's full attention for critical tasks

Best practices

Modals are disruptive by design and prevent users from accessing any other content on the page until the modal has been closed. Use modals for confirmations or conditional changes in the user interface. They should be temporary and not be used for information or actions that need to live in the UI in a persistent way.

Avoid using modals for displaying extensive amounts of information, and consider a Dialog instead if users are completing more complex tasks such as filling out forms, editing, ,or changing settings.

Modals should require that users take an action and should easily be dismissible.

Never, ever, display more than one Modal at a time.

Do not use more than two buttons (primary and secondary). This prevents unclear action hierarchy and crowding on mobile screens. In some cases however, a tertiary action may be appropriate.

When to use

For crucial actions or information, ensuring they serve a clear purpose in the user's journey.

To guide users through specific interactions, providing clarity and step-by-step guidance when needed.

To introduce information progressively through modals, revealing details as users advance in their tasks to avoid overwhelming them. For more complex tasks, consider a Dialog.

When not to use

When the amount of content requires users to scroll, consider a page instead.

If the user is expected to perform lengthy or complex tasks, consider a Dialog.

If there’s an existing Modal already displayed. Never use more than one Modal or Dialog at a time.

At points in the user journey that risk hindering progress, like checking out or payments.

Make sure to select an overlay solution fitting of the context. To sense check and support a decision, this Decision tree chart and high-level overview of available options might be helpful.

Anatomy

Listing all the separate elements of the modal

Backdrop – Can be blurred if displayed over gated content

Modal surface

Icon (only on attention modals)

Heading – The modal title

Content body – An overview of the modal's purpose and, optionally, controls to complete a simple task.

Footer – Contains a primary action and the ability to cancel and close the modal.

Close button

Variants

Default

Default modals are best reserved for immediate confirmations, conditional changes, or concise interactions that demand users' immediate attention without hindering the overall user experience.

✅ Do	🛑 Don’t
- Use to capture information from the user without having them leave the parent page. - Use to show additional information to the user without losing context of the parent page.	- Use to display error messages. - Use for lengthy and complex tasks or forms. - Large amounts of information.

The Attention modal should be used to interrupt a user flow until a specific action is taken. It is used to convey important messages that can't be ignored, like Toasts or Alerts.

This type of modal requires the user to acknowledge the information in the container before they can interact with outside content.

✅ Do	🛑 Don’t
- Use for confirming a permanent change, like deleting data. - Use to relay an important system message like a maintenance downtime window. - Use to prevent users from accidentally making irrevocable changes.	- Use to display error messages. - Use to display marketing content, like signing up for newsletters.

This type of modal is available so that designers are able to create Modals with content specific to the context they’re designing solutions. With this flexibility also comes the responsibility to make sure content guidelines are followed.

To use this variant, create a component with the custom content. Select the slot component and make an instance swap.

✅ Do	🛑 Don’t
- Make sure there’s a relevant header. - Make sure button placement and order is inline with the guidelines. - Add content only relevant to the purpose of the modal.	- Insert content that goes agains the guidelines and recommendations. - Place anything below the footer. - Resize the modal dimensions or spacing.

Sizes

Medium

The largest size for modals and typically the default size for desktop. All modals are responsive up to their max-width, which is the initial size straight out of the library.

Small

A more condensed version is ideal when smaller amounts of content is displayed, or for simple form elements. This size is also ideal for tablet sized screens. All modals are responsive up to their max-width, which is the initial size straight out of the library.

Mobile

Adapted for mobile screens, this variant aligns to the bottom and buttons are stacked. All modals are responsive up to their max-width, which is the initial size straight out of the library.

Behaviour

Dismissal

Modals close when users press the X button, a Cancel button, the Esc key, or, in some cases, when users click or tap the area outside the modal. On Mobile, a swipe-down gesture also closes the modal.

Animation & motion

All modals are animate as they enter and leave the view. As they enter, the backdrop fades in slightly before the container fades in with a slide up motion. This staggered effect should help the user to find focus more easily. When the modal leaves the view, the inverse staggered effect aims to help the user orient themselves back to the page content.

Overflow

Page overflow – the modal container expands below the visible window area and scrolling moves the entire container up and down, just like a page. This means that the headline and cross icon, as well as the footer with all actions, can be out of reach for users.

Container overflow – the modal container expands only within the visible window area. After that, headline and footer remain visible while the inner container becomes scrollable. This means actions are always available to users without any additional interaction.

Responsive behaviour

All modal types and sizes are responsive up to a max-width, which is the initial size straight out of the library. When adding contents, respect the dimensions set by the modal to maintain responsiveness.

Content guidelines

Limit the number of interactions in a modal.

Simplify by removing unnecessary elements or content that does not support the task.

Avoid multiple steps that require navigation within the modal dialog.

Avoid complex decision making that requires additional sources of information unavailable in the modal.

This modal dialog is responsive. When adding contents, respect the dimensions set by modal dialog to maintain responsiveness.

It's best to support multiple methods for dismissal.

Phrase confirmations as yes or no questions.

Supplemental text should provide more information, not just reword the title.

Align modal content directly with the user's task or decision at hand, avoiding unnecessary distractions.

Headline

Headline text should be concise (2-4 words and no more than one line) and describe the information or action the modal is presenting, and prioritise keywords.Godard gastropub

Body

Body copy should contain only valuable and relevant information that is both helpful and concise. Simple form elements can be added but avoid large and complex forms. Label elements with action verbs that indicate what happens when the element is selected. For example, label a select menu with Choose a region instead of Regions.

Button group

Avoid offering more than one primary action and a cancel action. In rare cases when necessary, primary and secondary buttons can be used with a tertiary button for cancel.

Alignment – Buttons are always aligned to the right on overlays, and to the left on page level.

Sort order – Always start with primary actions and continue down in order of importance.

Visualising the button alignment on modals

Gated content

Modals displayed over gated content have a blur effect on the backdrop layer. This prevents full access to content without loosing context to the page.

Go to effects, and add a 12 value background blur to the component.