# Drawer

Headless, unstyled bottom sheet with drag to dismiss, optional snap points, virtual keyboard handling and nesting. Shares the dialog behavior: portal, focus trap, scroll lock, dismissal and transitions. Ships no CSS: it writes `--cl-drawer-*` custom properties and `data-*` attributes for a styled layer to compose. `createDrawerHandle()` connects a root to a trigger rendered outside it.

## Use for

- the base for a styled bottom sheet
- a sheet the user swipes down to dismiss
- a sheet that rests at snap points, such as half and full height

## Practices

- Don't: Use the primitive in a feature. Use the styled `Drawer` from `src/components/drawer` instead.
- Do: Call `registerDrawerCssVars()` once in the styled layer so the drag custom properties do not inherit.
- Do: Set `data-drawer-no-drag` on any custom draggable inside the sheet. Native selects, range inputs, sliders and text selections are already excluded.
- Do: Pass `autoFocus` only when the sheet should focus its first field. By default focus goes to the sheet, so a touch open does not raise the keyboard.
- Do: Give `Drawer.Handle` a role and label if it should be announced. It is presentational; keyboard users close with Escape or `Drawer.Close`.
- Don't: Use it for a centered modal with no drag gesture. Use `Dialog` instead.

## API reference

### Drawer.Root

Holds the open, drag, snap and nesting state. Renders no element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` |  | Whether the drawer is open, when controlled. |
| `defaultOpen` | `boolean` | `false` | Whether the drawer is open on mount, when uncontrolled. |
| `onOpenChange` | `(open: boolean) => void` |  | Called with the new open state, including changes made through the handle. |
| `modal` | `boolean` | `true` | Traps focus and blocks the rest of the page. |
| `handle` | `DrawerHandle` |  | Connects a trigger rendered outside the root. From `createDrawerHandle()`. |
| `dismissible` | `boolean` | `true` | Lets a drag past the threshold, an outside press or Escape close the drawer. |
| `handleOnly` | `boolean` | `false` | Only a press that starts on `Drawer.Handle` starts a drag. |
| `snapPoints` | `number[]` |  | Ascending viewport fractions, from 0 to 1, the sheet can rest at. |
| `activeSnapPoint` | `number` |  | The index of the active snap point, when controlled. |
| `defaultActiveSnapPoint` | `number` | `the last` | The snap point index on open, when uncontrolled. |
| `onActiveSnapPointChange` | `(index: number) => void` |  | Called with the new snap point index. |
| `repositionInputs` | `boolean` | `true` | Keeps a focused field above the virtual keyboard. |
| `autoFocus` | `boolean` | `false` | Moves focus to the first field on open instead of the sheet. |

### Drawer.Trigger

A `button` that opens the drawer. Carries `data-open` or `data-closed`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `handle` | `DrawerHandle` |  | Drives a root rendered elsewhere. Not needed inside a root. |

### Drawer.Portal

Portals its children while the drawer is mounted.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `root` | `HTMLElement \| null \| React.RefObject<HTMLElement \| null>` | `` the `PortalProvider` container, else `document.body` `` | The element to portal into. |

### Drawer.Backdrop

A `div` behind the sheet. Carries `data-open` or `data-closed` and `data-swiping`, and gets `--cl-drawer-swipe-progress` to fade with the drag.

### Drawer.Viewport

A fixed full-viewport `div` that locks scroll. Carries `data-open` or `data-closed`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `lockScroll` | `boolean` | `true` | Locks body scroll while open. |

### Drawer.Popup

The sheet, a `role="dialog"` `div` that hosts the drag and the focus trap. Carries `data-swiping`, `data-snap`, `data-expanded`, `data-nested`, `data-nested-drawer-open` and `data-nested-drawer-swiping`, and the `--cl-drawer-*` drag, snap and nesting properties.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `finalFocus` | `FocusTarget` | `the trigger` | Where focus goes on close: `true`, `false`, a ref, or a function of the interaction type. |

### Drawer.Handle

The drag grip, a `div` with `data-drawer-handle`. The only drag target with `handleOnly`.

### Drawer.Title

An `h2` that names the sheet through `aria-labelledby`.

### Drawer.Description

A `p` that describes the sheet through `aria-describedby`.

### Drawer.Close

A `button` that closes the drawer.

## Examples

### A sheet with snap points

```tsx
<Drawer.Root snapPoints={[0.4, 1]} defaultActiveSnapPoint={0}>
  <Drawer.Trigger>Open</Drawer.Trigger>
  <Drawer.Portal>
    <Drawer.Backdrop />
    <Drawer.Viewport>
      <Drawer.Popup>
        <Drawer.Handle />
        <Drawer.Title>Filters</Drawer.Title>
        <Drawer.Close>Done</Drawer.Close>
      </Drawer.Popup>
    </Drawer.Viewport>
  </Drawer.Portal>
</Drawer.Root>
```

## Related

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