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
Drawerto 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
ImportModal 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). Adddata-autofocus to the element that should receive focus first.
Custom overlay and sizing
Props
ModalProps extends Mantine’s ModalProps.
Interaction states
Accessibility
TheModal component follows WAI-ARIA dialog modal recommendations.
- The dialog container receives
role="dialog"andaria-modal="true". - Setting the
titleprop generates anh2element inside the header;aria-labelledbyon the dialog element points at that heading id automatically. aria-describedbyon 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-autofocusto redirect initial focus to a specific element. - Pressing
EsccallsonClose. Do not disablecloseOnEscapeunless you provide an alternative dismiss mechanism. - Focus returns to the trigger element when the modal closes (
returnFocusistrueby default). - Use
closeButtonPropsto set a descriptivearia-labelon the close button when the button’s icon alone is not self-explanatory.