Skip to content

Design

A Modal is a focused container that appears above the page to display essential, interruptive, or task-related content without navigating away from the current view. It temporarily disables interaction with the underlying interface and requires the user to complete an action before returning to the previous context.

Anatomy

Section titled “Anatomy”
  1. Modal
  2. Frame
  3. Close button
  4. Content

When to use it

Section titled “When to use it”

Use the Modal when:

  • The user must take an action before continuing (confirm, acknowledge, complete a task).
  • You need to display content that requires full focus without distractions.
  • The interaction must not be missed (legal notices, blocking states).

Avoid the Modal when:

  • The information is optional or lightweight, and could sit inline or in a Popover.
  • The interruption breaks the user flow unnecessarily.
  • A non-blocking alternative (sheet, inline block, banner) would feel smoother.

Properties

Section titled “Properties”

Variant

Three composition shapes: Full screen (large surfaces such as comparison views), With image (a media-led modal where the visual anchors the message), and Without image (text-and-actions, the default for confirmations and forms).

Close button

Mandatory in every variant — a tertiary Button-Main at the LG size with the close icon. Optional dismissals like tapping outside the modal are not defined at component level and must not replace the visible close button.

Image

Optional media slot at the top of the modal, sourced from the Image component for consistent responsive behaviour. Recommended aspect ratio is 16:9 or 9:16.

Content slot

Mandatory and flexible — holds text, images, simple forms, or component instances. The modal supplies the container and behaviour; the slot’s content follows its own component guidelines.

Action area

Holds Primary, Secondary, Tertiary, and Link buttons drawn from the Button Main and Link Button components. Layout reflows from horizontal (desktop and tablet) to vertical (mobile, or whenever long labels need the room).

Backdrop

Mandatory — the modal sits above a semi-transparent Backdrop that blocks interaction with underlying content and isolates focus. Tokens for colour, opacity, and elevation live in the Backdrop component.

Platform considerations

Section titled “Platform considerations”

Desktop

The modal appears as a centred dialog with a backdrop. Horizontal action layout is the default, with buttons side-by-side following the standard hierarchy.

Tablet

Same centred dialog with horizontal actions. When labels are long enough to wrap, switch to vertical actions to keep the buttons readable.

Mobile

The modal automatically adopts a bottom-sheet layout, sliding up from the bottom. Actions stack vertically so the touch targets stay in the thumb zone. Structure, slot, close button, and action sets stay identical — only the layout changes.

Best practices

Section titled “Best practices”

Treat the modal as a focus tool — the moment it appears, nothing else should pull the user’s attention.

Do

Use a modal when the user must focus on a single task or piece of information, keep the close button visible and accessible, trap focus until the modal closes and return focus to the trigger on dismiss, and keep all content inside the modal reachable in a logical reading order.

Don't

Don’t use a modal for long or complex content (consider a dedicated page when copy grows), don’t stack multiple modals, and don’t rely on the backdrop alone for dismissal — the close button is mandatory.

Content guidelines

Section titled “Content guidelines”

The modal’s first line of copy carries the most weight — keep it short and name the decision the user needs to make. Body copy explains the consequence (“Deleting will remove all saved settings”); action buttons name the verb (“Delete”, “Cancel”). Avoid filler (“Are you sure you want to…?”) in favour of direct phrasing, and keep button labels consistent across modals so the choices recognise quickly.