> ## Documentation Index
> Fetch the complete documentation index at: https://clementineds.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Modal Component: Focus-Trapped Accessible Overlay Dialog

> Use Modal to interrupt the current page with a focus-trapped dialog for confirmations, short forms, or detail views that require a user decision.

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](https://mantine.dev/core/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

```tsx theme={null}
import { useState } from 'react';
import { Modal, Button, Text, Group } from '@clementine-ds/ui';

export function BasicModal() {
  const [opened, setOpened] = useState(false);

  return (
    <>
      <Modal
        opened={opened}
        onClose={() => setOpened(false)}
        title="Confirm deletion"
      >
        <Text size="sm">
          Are you sure you want to delete this project? This action cannot be undone.
        </Text>
        <Group mt="md" justify="flex-end">
          <Button variant="default" onClick={() => setOpened(false)}>
            Cancel
          </Button>
          <Button color="red" onClick={() => setOpened(false)}>
            Delete
          </Button>
        </Group>
      </Modal>

      <Button onClick={() => setOpened(true)}>Delete project</Button>
    </>
  );
}
```

### Centered modal

```tsx theme={null}
import { useState } from 'react';
import { Modal, Button } from '@clementine-ds/ui';

export function CenteredModal() {
  const [opened, setOpened] = useState(false);

  return (
    <>
      <Modal
        opened={opened}
        onClose={() => setOpened(false)}
        title="Edit profile"
        centered
      >
        {/* form content */}
      </Modal>

      <Button onClick={() => setOpened(true)}>Edit profile</Button>
    </>
  );
}
```

### 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.

```tsx theme={null}
import { useState } from 'react';
import { Modal, Button, TextInput } from '@clementine-ds/ui';

export function FocusedModal() {
  const [opened, setOpened] = useState(false);

  return (
    <>
      <Modal
        opened={opened}
        onClose={() => setOpened(false)}
        title="Invite teammate"
      >
        <TextInput
          data-autofocus
          label="Email address"
          placeholder="name@company.com"
        />
        <Button mt="md" onClick={() => setOpened(false)}>Send invite</Button>
      </Modal>

      <Button onClick={() => setOpened(true)}>Invite teammate</Button>
    </>
  );
}
```

### Custom overlay and sizing

```tsx theme={null}
import { useState } from 'react';
import { Modal, Button } from '@clementine-ds/ui';

export function CustomModal() {
  const [opened, setOpened] = useState(false);

  return (
    <>
      <Modal
        opened={opened}
        onClose={() => setOpened(false)}
        title="Document preview"
        size="xl"
        centered
        overlayProps={{ backgroundOpacity: 0.6, blur: 4 }}
      >
        {/* preview content */}
      </Modal>

      <Button onClick={() => setOpened(true)}>Preview document</Button>
    </>
  );
}
```

***

## Props

`ModalProps` extends Mantine's `ModalProps`.

| Prop | Type | Default | Description |
| - | - | - | - |
| `opened` | `boolean` | **required** | Controls whether the modal is visible. |
| `onClose` | `() => void` | **required** | Called when the modal requests to close (Esc key, overlay click, or close button). |
| `title` | `React.ReactNode` | — | Modal heading. Sets `aria-labelledby` on the dialog element. Always provide a title for accessibility. |
| `children` | `React.ReactNode` | — | Modal body content. |
| `centered` | `boolean` | — | Centers the modal vertically within the viewport. |
| `size` | `MantineSize \| number` | `"md"` | Controls the width of the content area. Accepts theme size keys (`"xs"` `"sm"` `"md"` `"lg"` `"xl"`) or any valid CSS width value. |
| `fullScreen` | `boolean` | — | Expands the modal to fill the entire screen. |
| `radius` | `MantineRadius \| number` | — | Border-radius of the modal content container. |
| `padding` | `MantineSpacing` | — | Padding applied to the header, body, and footer. |
| `shadow` | `MantineShadow` | — | Box-shadow of the modal content container. |
| `overlayProps` | `ModalBaseOverlayProps` | — | Props forwarded to the backdrop `Overlay` — use to set `backgroundOpacity`, `blur`, or custom styles. |
| `closeButtonProps` | `ModalBaseCloseButtonProps` | — | Props forwarded to the header close button (e.g., to set `aria-label` or a custom icon). |
| `withCloseButton` | `boolean` | `true` | When `false`, the close button in the header is not rendered. |
| `withOverlay` | `boolean` | `true` | When `false`, the backdrop overlay is not rendered. |
| `trapFocus` | `boolean` | `true` | When `false`, focus is not trapped inside the modal. **Disabling reduces accessibility.** |
| `closeOnEscape` | `boolean` | `true` | When `false`, pressing Esc does not close the modal. **Disabling reduces accessibility.** |
| `closeOnClickOutside` | `boolean` | `true` | When `false`, clicking the overlay does not close the modal. |
| `returnFocus` | `boolean` | `true` | When `false`, focus is not returned to the trigger element on close. **Disabling reduces accessibility.** |
| `lockScroll` | `boolean` | `true` | When `false`, page scroll is not locked while the modal is open. |
| `keepMounted` | `boolean` | — | When set, the modal's DOM subtree is not unmounted when closed — `display: none` is applied instead. |
| `transitionProps` | `TransitionProps` | `{ duration: 200, transition: 'fade-down' }` | Props forwarded to the `Transition` component that animates the modal. |
| `xOffset` | `MarginLeft<string \| number>` | — | Horizontal offset of the modal content area. |
| `yOffset` | `MarginTop<string \| number>` | — | Vertical offset of the modal content area. |
| `withinPortal` | `boolean` | `true` | When `false`, the modal renders in place rather than in a portal. |
| `portalProps` | `BasePortalProps` | — | Props forwarded to the `Portal` component. |
| `zIndex` | `string \| number` | — | `z-index` of the root element. |
| `id` | `string` | auto-generated | Id used to connect the modal content with its title and body elements for ARIA. |
| `scrollAreaComponent` | `ScrollAreaComponent` | — | Replaces the default scroll container inside the modal body. |
| `removeScrollProps` | `RemoveScrollProps` | — | Props forwarded to `react-remove-scroll` for customising scroll-lock behaviour. |
| `onEnterTransitionEnd` | `() => void` | — | Called after the open transition completes. |
| `onExitTransitionEnd` | `() => void` | — | Called after the close transition completes (useful for clearing state after the modal animates out). |

***

## Interaction states

| State | Description |
| - | - |
| `closed` | Modal is unmounted (or hidden with `display: none` when `keepMounted` is set). |
| `opening` | Enter transition is running; modal is animating into view. |
| `open` | Modal is fully visible; focus is trapped inside the dialog. |
| `closing` | Exit transition is running; modal is animating out of view. |

***

## Accessibility

The `Modal` component follows [WAI-ARIA dialog modal recommendations](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/dialog).

* 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.

```tsx theme={null}
// ✅ Always give the modal a title
<Modal opened={opened} onClose={close} title="Delete project">
  ...
</Modal>

// ✅ Label the close button when it needs context
<Modal
  opened={opened}
  onClose={close}
  title="Delete project"
  closeButtonProps={{ 'aria-label': 'Close delete confirmation' }}
>
  ...
</Modal>

// ❌ Missing title — screen readers cannot name the dialog
<Modal opened={opened} onClose={close}>
  ...
</Modal>
```

***

> [!WARNING]
>
> **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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.