# Drawer

A bottom sheet on the native `<dialog>`, dragged down to dismiss.

Source: https://www.zazz.sh/api/primitives/drawer/

## Installation

```bash
pnpm dlx zazz-ui add drawer
```

Also adds `fields`, `kbd`, `button`, `dialog`, which it depends on.

Run `zazz-ui init` first if the project has no `zazz/` folder yet.

## Examples

### Default

```html
<button data-ui="button" type="button" command="show-modal" commandfor="drawer-example-1">
  Open drawer
</button>
<dialog id="drawer-example-1" data-ui="drawer" closedby="any">
  <div data-drawer-slot="handle"></div>
  <div data-drawer-slot="content">
    <header data-drawer-slot="header">
      <h2
        style="
          --font-size: var(--font-size-lg);
          --font-weight: strong;
          --font-family: var(--font-family-heading);
        "
      >
        Notification settings
      </h2>
      <p style="--text: var(--color-muted-foreground)">
        Drag the drawer down, or flick it, to dismiss it.
      </p>
    </header>
    <div data-drawer-slot="body">
      <p>
        Scrolling content scrolls first. Once it is at the top, pulling down moves the drawer; the
        handle always does.
      </p>
    </div>
    <footer data-drawer-slot="footer">
      <button data-ui="button" type="button" commandfor="drawer-example-1" command="close">
        Cancel
      </button>
      <button
        data-ui="button"
        data-button-variant="primary"
        type="button"
        commandfor="drawer-example-1"
        command="close"
      >
        Save
      </button>
    </footer>
  </div>
</dialog>
```

### Responsive dialog

```html
<button data-ui="button" type="button" command="show-modal" commandfor="drawer-responsive-dialog-1">
  Open dialog
</button>
<dialog id="drawer-responsive-dialog-1" data-ui="dialog drawer" closedby="any">
  <div data-drawer-slot="handle"></div>
  <div data-dialog-slot="content">
    <header data-dialog-slot="header">
      <h2
        style="
          --font-size: var(--font-size-lg);
          --font-weight: strong;
          --font-family: var(--font-family-heading);
        "
      >
        Confirm your order
      </h2>
      <p style="--text: var(--color-muted-foreground)">
        A dialog on a desktop, and a drawer you can swipe away on a phone.
      </p>
    </header>
    <div data-dialog-slot="body">
      <p>The markup is a dialog with its usual slots, plus the drawer identity and a handle.</p>
    </div>
    <footer data-dialog-slot="footer">
      <button
        data-ui="button"
        type="button"
        commandfor="drawer-responsive-dialog-1"
        command="close"
      >
        Cancel
      </button>
      <button
        data-ui="button"
        data-button-variant="primary"
        type="button"
        commandfor="drawer-responsive-dialog-1"
        command="close"
      >
        Confirm
      </button>
    </footer>
  </div>
</dialog>
```

### Snap

```html
<button data-ui="button" type="button" command="show-modal" commandfor="drawer-snap-1">
  Open drawer
</button>
<dialog id="drawer-snap-1" data-ui="drawer" data-drawer-snap="12rem 0.5 1" closedby="any">
  <button type="button" data-drawer-slot="handle" aria-label="Resize drawer"></button>
  <div data-drawer-slot="content">
    <header data-drawer-slot="header">
      <h2
        style="
          --font-size: var(--font-size-lg);
          --font-weight: strong;
          --font-family: var(--font-family-heading);
        "
      >
        Nearby places
      </h2>
      <p style="--text: var(--color-muted-foreground)">
        Drag up for more, or press the handle to step through the sizes.
      </p>
    </header>
    <div data-drawer-slot="body">
      <p>The drawer rests at three heights. Its content scrolls once it is fully open.</p>
      <p>Flick down from the smallest height to close it.</p>
    </div>
  </div>
</dialog>
```

### Nested

```html
<button data-ui="button" type="button" command="show-modal" commandfor="drawer-nested-1">
  Open drawer
</button>
<dialog id="drawer-nested-1" data-ui="drawer" closedby="any">
  <div data-drawer-slot="handle"></div>
  <div data-drawer-slot="content">
    <header data-drawer-slot="header">
      <h2
        style="
          --font-size: var(--font-size-lg);
          --font-weight: strong;
          --font-family: var(--font-family-heading);
        "
      >
        Your order
      </h2>
      <p style="--text: var(--color-muted-foreground)">
        Open the second drawer: this one steps back behind it.
      </p>
    </header>
    <div data-drawer-slot="body">
      <p>Two items, arriving Thursday.</p>
    </div>
    <footer data-drawer-slot="footer">
      <button data-ui="button" type="button" commandfor="drawer-nested-1" command="close">
        Close
      </button>
      <button
        data-ui="button"
        data-button-variant="primary"
        type="button"
        command="show-modal"
        commandfor="drawer-nested-2"
      >
        Change address
      </button>
    </footer>
  </div>
</dialog>
<dialog id="drawer-nested-2" data-ui="drawer" closedby="any">
  <div data-drawer-slot="handle"></div>
  <div data-drawer-slot="content">
    <header data-drawer-slot="header">
      <h2
        style="
          --font-size: var(--font-size-lg);
          --font-weight: strong;
          --font-family: var(--font-family-heading);
        "
      >
        Delivery address
      </h2>
      <p style="--text: var(--color-muted-foreground)">
        Drag this drawer down and the one behind follows it back.
      </p>
    </header>
    <div data-drawer-slot="body">
      <p>14 Harbour Street, Flat 3.</p>
    </div>
    <footer data-drawer-slot="footer">
      <button
        data-ui="button"
        data-button-variant="primary"
        type="button"
        commandfor="drawer-nested-2"
        command="close"
      >
        Done
      </button>
    </footer>
  </div>
</dialog>
```

### Indent

```html
<ui-drawer-indent style="--p: 6">
  <button data-ui="button" type="button" command="show-modal" commandfor="drawer-indent-1">
    Open drawer
  </button>
</ui-drawer-indent>
<dialog id="drawer-indent-1" data-ui="drawer" closedby="any">
  <div data-drawer-slot="handle"></div>
  <div data-drawer-slot="content">
    <header data-drawer-slot="header">
      <h2
        style="
          --font-size: var(--font-size-lg);
          --font-weight: strong;
          --font-family: var(--font-family-heading);
        "
      >
        Share this page
      </h2>
      <p style="--text: var(--color-muted-foreground)">
        The page behind steps back while the drawer is open, and follows as you drag it down.
      </p>
    </header>
    <div data-drawer-slot="body">
      <p>Wrap the page in the indent element once; every drawer on the page uses it.</p>
    </div>
  </div>
</dialog>
```

## Behavior

`primitives/drawer/drawer.js`

Drawer: drag-to-dismiss for `<dialog data-ui="drawer">` bottom sheets.
A drawer is a native modal `<dialog>`, opened and closed like
any other (`command="show-modal"`, `command="close"`, Esc, the backdrop with
`closedby="any"`). This script adds the gesture: drag the drawer down and
let go to dismiss it.

- `data-ui="drawer"` is a drawer on every device.
- `data-ui="dialog drawer"` is a drawer below the `sm` band on a touch
  screen, and a plain dialog (no dragging) everywhere else.

While the pointer is down the drawer follows it 1:1 and the backdrop fades
with it. Letting go past a quarter of the drawer's height, or with a quick
downward flick, slides it off the bottom edge and then closes it through
`requestClose()`, so `cancel` and `close` fire as they do for Esc; anything
less returns it to rest. Until it has slid out it can be caught again. Pulling it up
past its resting place meets resistance.

A drag starts anywhere on the drawer except on form fields, selected text,
and anything inside `[data-ui-no-drag]`. Inside scrolling content it starts
only once that content is scrolled to the top and the pointer moves down,
so the body scrolls first and the drawer follows; the handle
(`data-drawer-slot="handle"`) always drags. There is no custom element and
nothing to initialize: the script binds a drawer when it opens.

**Snap points.** `data-drawer-snap="148px 0.5 1"` gives the drawer resting
heights, smallest first: a number up to 1 is a share of the drawer's full
height, a `px` or `rem` length is a visible height. It opens at the first.
Letting go settles on the nearest; a flick moves one stop in its direction,
a very fast one goes all the way (or one stop, with
`data-drawer-snap-sequential`), and from the lowest stop a flick or enough
travel downward closes the drawer. Below the largest stop the drawer takes
every vertical drag and its content does not scroll. A click on the handle
steps to the next stop; make the handle a `<button>` to give the keyboard
the same. Each change fires `zazz:drawer-snap` (`detail.index`,
`detail.value` in px), `data-drawer-state` carries `expanded` at the largest
stop, and `snapDrawer(dialog, index)` moves it from script.

**The software keyboard.** A phone lays a drawer out against the full
screen, which the keyboard does not shrink. While a field in the front
drawer has the keyboard up, the drawer's content ends at the keyboard's top
edge (its surface runs on underneath), the focused field scrolls into what
is still visible, and the page behind stays where it was. Nothing to author.

**Stacked drawers.** A drawer opened over another scales the one behind back
and lifts it, and that one follows as the front drawer is dragged. Nothing
to author: the script counts the open drawers.

**Indent.** Wrap the page in `<ui-drawer-indent>` (or put
`data-ui="drawer-indent"` on its wrapper) and it scales back behind any open
drawer, with rounded top corners, and follows the drag of the last one. Only
transforms animate. While indented the wrapper is transformed, so a
`position: fixed` element inside it moves with the page; `position: sticky`
is unaffected.

Events: `zazz:dialog-close`, `zazz:dialog-open`, `zazz:drawer-snap`

## Drawer everywhere, or only on a phone

`data-ui="drawer"` on a `<dialog>` is a drawer on every device: it rises from the bottom edge, spans the full width of the screen, and can be dragged with a mouse as well as a finger. It has its own slots, `data-drawer-slot="content"`, `header`, `body`, `footer`, and `close`, which lay out as the dialog's do.

`data-ui="dialog drawer"` is a [dialog](/api/primitives/dialog/) that turns into a drawer below the `sm` band on a touch screen, the same test the dialog uses for its phone size. Everywhere else it is the plain dialog at the width its `data-dialog-size` gives it, and it does not drag. Keep the dialog's slots (`data-dialog-slot`), and add the handle:

```html
<dialog id="confirm" data-ui="dialog drawer" closedby="any">
  <div data-drawer-slot="handle"></div>
  <div data-dialog-slot="content">…</div>
</dialog>
```

In drawer mode both forms run edge to edge. To float a narrower sheet, cap `--ui-drawer-w` with a layout band: `--ui-drawer-w: min(var(--layout-sm), 100%)`.

A drawer takes the place of the dialog's phone size, so `--ui-dialog-mobile-size` does not apply to it. The handle is optional and shows only in drawer mode.

## Dragging and scrolling

The whole drawer is the drag surface. Letting go past a quarter of its height closes it, and so does a quick downward flick over any distance; less than that and it returns to rest. Closing goes through `requestClose()`, so a `cancel` listener can keep the drawer open, as it can for Esc.

Content that scrolls takes the gesture first. A pull moves the drawer only once the content under the finger is scrolled to the top, and only downward; the handle drags the drawer wherever the content is. Form fields and selected text never start a drag. To keep the drawer still under something else that needs the pointer (a map, a slider, a canvas), mark it:

```html
<div data-ui-no-drag>…</div>
```

The open and close motion is the dialog's transition with the drawer's own timing: `--ui-drawer-transition-duration` (twice the default duration) and `--ui-drawer-transition-timing-function`. With `prefers-reduced-motion` the duration is zero, as it is for every dialog; the drawer still follows the pointer while it is dragged.

## Forms and the on-screen keyboard

On a phone, the keyboard covers the bottom of the screen without making the page any shorter, so a drawer would sit partly under it. While a field in the front drawer has the keyboard up, the drawer's content ends at the keyboard's top edge, with its surface carrying on underneath, and the focused field scrolls into the part that is still visible. The page behind keeps its scroll position. There is nothing to author.

## Snap points

`data-drawer-snap` gives a drawer more than one resting height. List them smallest first, separated by spaces: a number up to `1` is a share of the drawer's full height, and a `px` or `rem` length is a visible height.

```html
<dialog id="places" data-ui="drawer" data-drawer-snap="12rem 0.5 1" closedby="any">
  <button type="button" data-drawer-slot="handle" aria-label="Resize drawer"></button>
  <div data-drawer-slot="content">…</div>
</dialog>
```

The drawer opens at the first stop. Letting go settles it on the nearest one; a flick moves it one stop in the flick's direction, and a very fast flick goes all the way open or closed. Add `data-drawer-snap-sequential` to make a fast flick move one stop as well. From the smallest stop, a downward flick or enough travel closes the drawer.

Below its largest stop the drawer takes every vertical drag and its content does not scroll; at the largest stop content scrolls first, as it does without snap points. A click on the handle steps to the next stop and wraps to the first. Make the handle a `<button>` with an `aria-label`, as above, so the keyboard can do the same.

The backdrop stays full at every stop, because the drawer is a modal dialog and the page behind it is inert. It fades only as the drawer is dragged below the smallest stop.

| Read or write | How |
| --- | --- |
| The drawer reached a stop | `zazz:drawer-snap` on the dialog, bubbling; `event.detail.index` and `event.detail.value` (visible height in px) |
| It is at the largest stop | `data-drawer-state~="expanded"` (otherwise `partial`) |
| Move it from script | `import { snapDrawer } from "@zazz-ui/core/primitives/drawer/drawer.js"`, then `snapDrawer(dialog, index)` |

## Stacked drawers

A drawer opened while another is open sits in front of it. The one behind scales back and lifts so its top edge shows, and it follows as the front drawer is dragged down. Esc and the backdrop close the front drawer first. There is nothing to author: open the second drawer from the first with the usual `command="show-modal"`.

`--ui-drawer-stack-scale` (default `0.05`) is how much each drawer in front shrinks the one behind, and `--ui-drawer-stack-lift` how far it lifts. The second drawer adds no dimming of its own; set `--ui-drawer-nested-backdrop-color` to give it some.

## Indenting the page

Wrap the page in `<ui-drawer-indent>` (or put `data-ui="drawer-indent"` on the element that already wraps it), and the page scales back behind any open drawer, with rounded top corners, and follows the last drawer as it is dragged down.

```html
<body>
  <ui-drawer-indent>
    <header>…</header>
    <main>…</main>
  </ui-drawer-indent>

  <dialog id="share" data-ui="drawer" closedby="any">…</dialog>
</body>
```

Drawers can sit inside the wrapper or beside it. The wrapper paints the page background (`--ui-drawer-indent-bg`), and the `<body>` takes the backing color (`--ui-drawer-indent-backing`, black by default) while the page is indented. Set the indent hooks on `:root`, since the body reads the backing color too.

| Hook | What it sets | Default |
| --- | --- | --- |
| `--ui-drawer-indent-inset` | How far each side of the page pulls in | 3 spacing units |
| `--ui-drawer-indent-offset` | How far the page drops from the top | the top safe-area inset plus `--space-sm` |
| `--ui-drawer-indent-radius` | The radius of the page's top corners | `--ui-drawer-radius` |

Only `scale` and `translate` animate. The corner radius is two small corner pieces that grow from the corners, so no `border-radius` or clip is animated and the page is not repainted as it moves. The corners follow `--radius-corner-shape` in browsers that support `corner-shape` and are round elsewhere.

Two limits come with scaling the page:

- While a drawer is open the wrapper is transformed, so a `position: fixed` element inside it is positioned against the wrapper and moves with the page. Use `position: sticky` for headers, or keep fixed elements outside the wrapper.
- A `dialog drawer` indents the page only in drawer mode, never as a desktop dialog.

## Attributes

| Attribute | Kind | Values |
| --- | --- | --- |
| `data-ui="drawer-indent"` | identity | free value |
| `data-ui="drawer"` | identity | free value |
| `<ui-drawer-indent>` | tag | free value |
| `data-drawer-slot` | slot | `body` `close` `content` `footer` `handle` `header` |
| `data-drawer-indent-state` | state | `active` `dragging` `on` |
| `data-drawer-state` | state | `dragging` `following` `nested` `partial` `stacked` |
| `data-drawer-snap` | config | free value |
| `data-drawer-snap-sequential` | config | free value |

Requires: dialog, button.

## Hooks

| Hook | Default | State |
| --- | --- | --- |
| `--ui-drawer-bg` | `var(--ui-dialog-bg)` | — |
| `--ui-drawer-corner-shape` | `var(--ui-dialog-corner-shape)` | — |
| `--ui-drawer-handle-bg` | `var(--color-muted)` | — |
| `--ui-drawer-handle-bg--active` | `var(--color-muted-foreground)` | active |
| `--ui-drawer-handle-bg--dragging` | `var(--color-foreground)` | dragging |
| `--ui-drawer-handle-bg--hover` | `var(--color-muted-foreground)` | hover |
| `--ui-drawer-handle-h` | `calc(var(--spacing) * 1.25)` | — |
| `--ui-drawer-handle-w` | `calc(var(--spacing) * 12)` | — |
| `--ui-drawer-indent-backing` | `var(--color-black)` | — |
| `--ui-drawer-indent-bg` | `var(--color-background)` | — |
| `--ui-drawer-indent-inset` | `calc(var(--spacing) * 3)` | — |
| `--ui-drawer-indent-offset` | `calc(env(safe-area-inset-top, 0px) + var(--space-sm))` | — |
| `--ui-drawer-indent-radius` | `var(--ui-drawer-radius)` | — |
| `--ui-drawer-max-h` | `calc(100dvb - var(--space-lg))` | — |
| `--ui-drawer-nested-backdrop-color` | `transparent` | — |
| `--ui-drawer-radius` | `var(--radius-xl)` | — |
| `--ui-drawer-shadow` | `var(--shadow-lg)` | — |
| `--ui-drawer-stack-lift` | `var(--space-sm)` | — |
| `--ui-drawer-stack-scale` | `0.05` | — |
| `--ui-drawer-text` | `var(--ui-dialog-text)` | — |
| `--ui-drawer-transition-duration` | `calc(var(--default-transition-duration) * 2)` | — |
| `--ui-drawer-transition-timing-function` | `cubic-bezier(0.32, 0.72, 0, 1)` | — |
| `--ui-drawer-w` | `100%` | — |
