# Modals and Drawers

Source: https://payloadcms.com/docs/ui-components/modals-and-drawers

Payload provides several overlay surfaces for focused actions and supporting content. The Admin Panel supplies the modal context these components use.

## Import

```tsx
import {
  ConfirmationModal,
  Drawer,
  DrawerContentContainer,
  DrawerToggler,
  FullscreenModal,
  Modal,
  useModal,
} from '@payloadcms/ui'
```

## Confirmation modal

**Implementation**

```tsx
const modalSlug = 'confirm-action'
const { openModal } = useModal()

<Button onClick={() => openModal(modalSlug)}>Open confirmation modal</Button>
<ConfirmationModal
  body="Confirm before continuing with this action."
  cancelLabel="Cancel"
  confirmLabel="Confirm"
  heading="Confirm action"
  modalSlug={modalSlug}
  onConfirm={() => performAction()}
/>
```

**Styling**

Target the ConfirmationModal wrapper to give confirmation dialogs a branded panel treatment.

```css
.confirmation-modal__wrapper {
  background: #ffffff;
  border: 1px solid #c8c0ff;
  border-radius: 12px;
  box-shadow: 0 24px 60px rgb(33 27 77 / 20%);
}
```

- `background`: Dialog panel surface.
- `border`: Dialog panel outline.
- `box-shadow`: Dialog elevation.

Give the trigger and modal the same `modalSlug`. Call `openModal` with that slug to display the modal. `ConfirmationModal` closes itself after `onConfirm` resolves or when the user cancels.

## Drawer

**Implementation**

```tsx
const drawerSlug = 'example-drawer'
const { closeModal, openModal } = useModal()

<Button onClick={() => openModal(drawerSlug)}>Open drawer</Button>
<Drawer slug={drawerSlug} title="Drawer example">
  <DrawerContentContainer>
    <p>Place supporting information or controls related to the current view here.</p>
    <Button
      buttonStyle="secondary"
      onClick={() => closeModal(drawerSlug)}
    >
      Close drawer
    </Button>
  </DrawerContentContainer>
</Drawer>
```

**Styling**

Customize the Drawer panel and dismiss region separately while preserving its positioning and transition behavior.

```css
.drawer__content {
  background: #faf9ff;
  border-left: 1px solid #c8c0ff;
}

.drawer__close {
  background: #211b4d;
}
```

- `background`: Drawer panel or dismiss-region surface.
- `border-left`: Panel edge in left-to-right layouts.

Use `DrawerToggler` or `openModal` to open a `Drawer`. The trigger and drawer must share the same `slug`.

`DrawerContentContainer` adds the standard content spacing used inside Payload drawers. Set `gutter={false}` on `Drawer` when the drawer's contents manage their own horizontal spacing.

## Choosing a surface

- Use `ConfirmationModal` to confirm a focused action.
- Use `Drawer` for supporting content that should remain connected to the current view.
- Use `Modal` for a custom dialog and `FullscreenModal` when the content needs the full viewport.
- Use `ItemsDrawer` when the user needs to pick from a searchable list of Blocks or Widgets, as Payload does when adding a row to a Blocks field.
- Use the `useDocumentDrawer` or `useListDrawer` hooks for document selection. Each returns the drawer, its toggler, and the drawer's state.

## Common props

These are the props most commonly used. See the exported types in `@payloadcms/ui` for the complete list.

### ConfirmationModal

| Prop              | Type                          | Default | Description                                             |
| ----------------- | ----------------------------- | ------- | ------------------------------------------------------- |
| `modalSlug` \*    | `string`                      | —       | Connects the modal to its trigger.                      |
| `heading` \*      | `ReactNode`                   | —       | Displays the modal heading.                             |
| `body` \*         | `ReactNode`                   | —       | Displays the confirmation message.                      |
| `onConfirm` \*    | `() => Promise<void> \| void` | —       | Runs when the user confirms the action.                 |
| `onCancel`        | `() => void`                  | —       | Runs after the user cancels the action.                 |
| `confirmLabel`    | `string`                      | —       | Replaces the translated confirm label.                  |
| `confirmingLabel` | `string`                      | —       | Replaces the label shown while confirmation is pending. |
| `cancelLabel`     | `string`                      | —       | Replaces the translated cancel label.                   |

### Drawer#drawer-props

| Prop          | Type        | Default | Description                                         |
| ------------- | ----------- | ------- | --------------------------------------------------- |
| `slug` \*     | `string`    | —       | Connects the drawer to its trigger.                 |
| `title`       | `string`    | —       | Displays the default drawer heading.                |
| `children` \* | `ReactNode` | —       | Renders the drawer content.                         |
| `gutter`      | `boolean`   | `true`  | Applies Payload's horizontal gutter to the content. |
| `Header`      | `ReactNode` | —       | Replaces the default drawer header.                 |
| `hoverTitle`  | `boolean`   | —       | Adds the title as a native tooltip on the heading.  |

_\* An asterisk denotes that a prop is required._

## Provider requirements

These components use the modal, translation, and drawer-depth contexts supplied by the Payload Admin Panel. When composing them outside the Admin Panel, provide the equivalent contexts before rendering the components.