# Drawer

A bottom sheet that rises from the bottom of the screen, with a scrim and a grip. Drag it down, press Escape or press outside to dismiss. Wraps the headless `Drawer` primitive.

## Use for

- a bottom sheet on a small screen
- a draggable panel with snap points
- a sheet opened from inside a card or profile dialog

## Practices

- Do: Name the sheet with `Drawer.Title`, and describe it with `Drawer.Description`.
- Do: Pass `autoFocus` only when the sheet opens to a field the user types in at once. It is off so opening on touch does not raise the keyboard.

## API reference

### Drawer.Root

Holds the open state, dismissal, snap points and drag policy. Renders no element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` |  | Whether the sheet is open, when controlled. |
| `defaultOpen` | `boolean` |  | Whether the sheet is open on mount. |
| `onOpenChange` | `(open: boolean) => void` |  | Called when the sheet opens or closes. |
| `modal` | `boolean` | `true` | Traps focus and blocks the rest of the page. |
| `handle` | `HeadlessDrawerProps['handle']` |  | Imperative handle for a trigger rendered outside `Drawer.Root`. |
| `snapPoints` | `number[]` |  | Ascending fractions (0 to 1) of the viewport the sheet rests at. |
| `activeSnapPoint` | `number` |  | The active snap point index, when controlled. |
| `defaultActiveSnapPoint` | `number` | `the last, most open` | The active snap point index on mount. |
| `onActiveSnapPointChange` | `(index: number) => void` |  | Called with the new snap point index. |
| `dismissible` | `boolean` | `true` | Lets a downward release past the threshold, or an outside press, close it. |
| `handleOnly` | `boolean` | `false` | Starts a drag only from the grip. |
| `repositionInputs` | `boolean` | `true` | Keeps a focused field above the virtual keyboard. |
| `autoFocus` | `boolean` | `false` | Moves focus into the sheet on open. |

### Drawer.Trigger

The headless trigger button that opens the sheet.

### Drawer.Popup

The sheet, with its portal, viewport (`cl-drawer-viewport`), scrim (`cl-drawer-backdrop`, `data-nested` inside a dialog), grip (`cl-drawer-handle`, `cl-drawer-grip`) and content box (`cl-drawer-content`).

Slot: `cl-drawer-popup`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `finalFocus` | `DrawerFocusTarget` | `the trigger` | Where focus returns when the sheet closes. |

### Drawer.Title

The headless title the sheet is labelled by.

### Drawer.Description

The headless description the sheet is described by.

### Drawer.Close

The headless button that closes the sheet from inside.

## Examples

### A sheet

```tsx
<Drawer.Root>
  <Drawer.Trigger>{m.open}</Drawer.Trigger>
  <Drawer.Popup>
    <Drawer.Title>{m.title}</Drawer.Title>
    <Drawer.Description>{m.description}</Drawer.Description>
    <Drawer.Close>{m.done}</Drawer.Close>
  </Drawer.Popup>
</Drawer.Root>
```

## Related

- [Dialog](/docs/components/dialog.md)
