Skip to main content

Modal

(Last update: 4 Apr 2025)

Overview​

Definition​

Modals are temporary UI overlays that require user interaction before proceeding. A modal is used to reveal critical information, show information without losing context, or when the system requires a user response.

Live demo​

[ Add Storybook ]

Anatomy​

  1. Backdrop: Transparent overlay that contains the modal dialog.
  2. Container: Modal dialog container.
  3. Title: A question or descriptive phrase that conveys an overview of the purpose.
  4. Message: Text content indicating the purpose and potential next steps.
  5. Dismissal: Button element to dismiss the modal.
  6. Actions: Buttons used to provide explicit action(s) the user can take to either close the modal or continue with a task.

Variants​

Standard Modal

  • Typically used for notifications or simple choices

Confirmation Modal

  • Short, direct message with clear affirmative/negative options (e.g., “Delete”, “Cancel”)

Form Modal

  • Includes fields for user input
  • Often includes validation logic

Full-screen Modal

  • Occupies the entire viewport
  • Ideal for immersive tasks like wizards, settings, or multi-step workflows
  • Close icon and breadcrumb or progress indicator recommended

Multi-step Modal

  • Used for progressive disclosures (e.g., change contract, edit place of work)
  • ncludes a step indicator, “Next” and “Back” buttons
  • Optionally supports validation per step

Sizes​

  • Extra Small (xs) – 360 px
  • Small (sm) – 540 px
  • Normal (base) – 740 px
  • Large (lg) – 900 px
  • Extra Large (xl) – 1280 px

Guidelines​

When to use​

  • For necessary actions outside the main flow.
  • When the action doesn’t benefit from the context of the current screen.
  • To interrupt the flow and force attention.

When not to use​

  • When you have only a single simple action—use a dialog.
  • For little information that doesn’t disrupt the main flow—use a popover.
  • For a temporary message without actions—use a toast.
  • Nest modals within modals
  • Use modals for large amounts of text or data

Layout guidance​

[ TBC ]

Interactions & Behaviour​

Open on user action​

Modals disrupt the main flow. If they come as a surprise, they’re more likely to be dismissed. Only open a modal after the user has taken an action so it’s clear why it was triggered.

Direct user with the title​

A modal title sets the context for everything inside and also stays fixed at the top if the modal scrolls down. So the title should make it clear what the modal relates to and what actions might be expected of the user. Keep it short and focused on either an action (verb) or a category (noun).

Allow users to close​

Users want to feel in control of their actions. Since modals act as interruptions, they can invoke negative feelings in users. Make sure users feel in control by offering them a clear option to close the modal and get back to the main flow.

Modals should always include a close button in the footer (with a name appropriate to the situation).

If you have a primary action in the modal footer that results in a system change, then you should have a Cancel button. If the modal is providing information and there is no action to take, you should have a Close button.

If there is only one option and it's ‘Close’ (not a primary action) then the close function can be handled by the top right X, and buttons in the footer are not mandatory. Desktop modals should include a close button in the upper right unless you need an explicit close (such as for cookie consent).

The option to close the modal by clicking the overlay is only applicable for informational or non-critical modals (eg. Welcome, Subscribe now). Do not allow overlay dismissal if the modal requires confirmation, data input, multi-steps or explicit acknowledgement.

Button position and behaviour​

  1. If there is only one button on the modal footer, position it at the bottom-right.
  2. If there are two action buttons, position the primary action on the bottom-right (e.g., “Save”, “Confirm”), and secondary or cancel action on the bottom-left.
  3. Dim the primary button if all required information is not completed.
  4. Avoid too many action buttons (2–3 max)
  5. *[ add image ] *

Scroll Behaviour​

Disable background scroll when modal is open. Internal modal content can scroll independently.

CONTENT​

Keep content clear and concise.

Provide clear differentiation between primary, secondary and danger actions.

ACCESSIBILITY​

Keyboard Navigation​

  • Tab and Shift + Tab cycle through focusable elements.
  • Modal opens with focus on first input or action buttons.
  • ESC closes modal.

Screen Readers​

  • Ensure modal content is read as a single context.
  • Do not read background content when modal is open.