Skip to main content
The Modal component renders a blocking overlay dialog that interrupts the current page to collect a decision, display critical information, or present a short-form workflow. It is Status: Draft and is backed by Mantine’s Modal primitive. Clementine exports it from @clementine-ds/ui with the Clementine theme applied.

When to use

  • You need the user to make a decision before continuing — for example, a destructive-action confirmation (“Delete this project?”).
  • A compact form that doesn’t warrant a full page navigation (e.g., editing a name, inviting a teammate).
  • Showing detail content that supplements the current view without replacing it entirely (e.g., a preview of an attachment).

When not to use

  • Most flows belong inline. If the content can reasonably live on the same page or on a dedicated route, don’t reach for a modal. Overusing modals interrupts user flow and degrades accessibility for keyboard and screen-reader users.
  • Multistep wizards with many fields — use a dedicated page or a Drawer to give the user more space.
  • Non-blocking contextual information — use a Tooltip, Popover, or inline message instead.
  • Navigation — links and page transitions should change the URL, not open modals.

Usage

Import Modal from @clementine-ds/ui. Manage the opened state yourself and pass opened and onClose to the component.

Basic modal

Centered modal

Controlling initial focus

Modal traps focus on open. By default it focuses the first focusable element (usually the close button). Add data-autofocus to the element that should receive focus first.

Custom overlay and sizing


Props

ModalProps extends Mantine’s ModalProps.

Interaction states


Accessibility

The Modal component follows WAI-ARIA dialog modal recommendations.
  • The dialog container receives role="dialog" and aria-modal="true".
  • Setting the title prop generates an h2 element inside the header; aria-labelledby on the dialog element points at that heading id automatically.
  • aria-describedby on the dialog points at the body content element.
  • Focus is trapped inside the dialog while it is open. The first focusable element receives focus on open (the close button by default). Add data-autofocus to redirect initial focus to a specific element.
  • Pressing Esc calls onClose. Do not disable closeOnEscape unless you provide an alternative dismiss mechanism.
  • Focus returns to the trigger element when the modal closes (returnFocus is true by default).
  • Use closeButtonProps to set a descriptive aria-label on the close button when the button’s icon alone is not self-explanatory.

Draft status. The Modal component is currently Draft. Focus-trap behaviour and Esc-to-close need verification — particularly when the modal is triggered from within a React portal. Confirm Mantine’s focus trap correctly restores focus to the trigger element before shipping to production.