# Drawer

> Source: https://design.nanatec.co.ke/components/drawer/
> A panel that slides in from an edge, built on the native `<dialog>` element. `temporary` (default) shows a modal with a backdrop and focus trap; `persistent` shows a non-modal panel that doesn't block the page.

A panel that slides in from an edge, built on the native `<dialog>` element.
`temporary` (default) shows a modal with a backdrop and focus trap; `persistent`
shows a non-modal panel that doesn't block the page.

## Preview

Click to open. The drawer is a native modal — backdrop, focus trap, and closes
on <kbd>Esc</kbd>, backdrop click, or the close button.

```html
<nana-button onclick="this.parentElement.querySelector('nana-drawer').show()">Open drawer</nana-button>
<nana-drawer placement="end" size="md" label="Filters" close-button>
  <p style="margin:0 0 1rem">Refine your results.</p>
  <nana-input label="Keyword" placeholder="Search…" style="width:100%"></nana-input>
  <nana-button slot="footer" variant="ghost" onclick="this.closest('nana-drawer').close()">Cancel</nana-button>
  <nana-button slot="footer" variant="primary" onclick="this.closest('nana-drawer').close()">Apply</nana-button>
</nana-drawer>
```

## Installation

```bash
npm install @nana-tec/ui-components
```

## Import

```js
import "@nana-tec/ui-components/drawer";
```

## Basic usage

Open with the `open` attribute or `.show()`; close with `.close()`, the close
button, backdrop click, or <kbd>Esc</kbd>.

```html
<nana-button onclick="document.getElementById('d').show()">Open</nana-button>

<nana-drawer id="d" placement="end" label="Settings" close-button>
  <p>Drawer body content.</p>
  <nana-button slot="footer" variant="primary" onclick="document.getElementById('d').close()">
    Save
  </nana-button>
</nana-drawer>
```

## Placements

The `placement` attribute picks the edge — `start`, `end` (default), `top`, or
`bottom`.

```html
<nana-button onclick="this.nextElementSibling.show()">Start</nana-button>
<nana-drawer placement="start" label="Start" close-button>Slides from the start edge.</nana-drawer>
<nana-button onclick="this.nextElementSibling.show()">End</nana-button>
<nana-drawer placement="end" label="End" close-button>Slides from the end edge.</nana-drawer>
<nana-button onclick="this.nextElementSibling.show()">Top</nana-button>
<nana-drawer placement="top" label="Top" close-button>Slides from the top.</nana-drawer>
<nana-button onclick="this.nextElementSibling.show()">Bottom</nana-button>
<nana-drawer placement="bottom" label="Bottom" close-button>Slides from the bottom.</nana-drawer>
```

## Sizes

`size` sets the panel's width (`start`/`end`) or height (`top`/`bottom`):
`sm` (16rem), `md` (20rem, default), `lg` (28rem), `xl` (36rem), or `full`
(100%). Override any of them with `--nana-drawer-size`.

```html
<nana-button onclick="this.nextElementSibling.show()">Small</nana-button>
<nana-drawer placement="end" size="sm" label="Small · 16rem" close-button>The small drawer.</nana-drawer>
<nana-button onclick="this.nextElementSibling.show()">Medium</nana-button>
<nana-drawer placement="end" size="md" label="Medium · 20rem" close-button>The default drawer.</nana-drawer>
<nana-button onclick="this.nextElementSibling.show()">Large</nana-button>
<nana-drawer placement="end" size="lg" label="Large · 28rem" close-button>The large drawer.</nana-drawer>
<nana-button onclick="this.nextElementSibling.show()">XL</nana-button>
<nana-drawer placement="end" size="xl" label="XL · 36rem" close-button>The extra-large drawer.</nana-drawer>
<nana-button onclick="this.nextElementSibling.show()">Full</nana-button>
<nana-drawer placement="end" size="full" label="Full · 100%" close-button>The full-size drawer.</nana-drawer>
```

## Header, footer & close button

Give it a title with `label` (and `close-button` for a built-in ✕), or take
full control with the `header` and `footer` slots.

```html
<nana-drawer placement="end" close-button>
  <div slot="header">Custom header</div>

  Body content…

  <div slot="footer">
    <nana-button variant="ghost">Cancel</nana-button>
    <nana-button variant="primary">Save</nana-button>
  </div>
</nana-drawer>
```

## Persistent (non-modal)

Add `persistent` for a non-modal panel that doesn't dim or block the page — ideal
for a filter rail or navigation that stays open alongside the content.

```html
<nana-drawer placement="start" persistent open label="Filters">
  <!-- stays open; the page remains interactive -->
</nana-drawer>
```

## API

## Methods

| Method | Description |
|---|---|
| `show()` | Open the drawer |
| `close()` | Close the drawer |

## Events

| Event | Description |
|---|---|
| `nana-open` | Fired after opening |
| `nana-close` | Fired after closing |

## Slots

| Slot | Description |
|---|---|
| `(default)` | Drawer body content |
| `header` | Custom header (overrides the `label` attribute) |
| `footer` | Footer actions, pinned to the bottom |

## CSS Variables

| Variable | Description |
|---|---|
| `--nana-drawer-size` | Panel width (start/end) or height (top/bottom) |

## CSS Parts

| Part | Description |
|---|---|
| `dialog` | The native `<dialog>` element |
| `panel` | The sliding panel |
| `header` | The header row |
| `close-button` | The built-in close button |

## Accessibility

<ul class="a11y-grid not-content">
  <li>Native dialog semantics</li>
  <li>Focus trapped while open</li>
  <li>Escape to close</li>
  <li>Focus returns to trigger</li>
  <li>WCAG 2.2 AA contrast</li>
</ul>

## Related components

<ul class="related not-content">
  <li><a href="/components/dialog/">Dialog</a></li>
  <li><a href="/components/popup/">Popup</a></li>
  <li><a href="/components/tooltip/">Tooltip</a></li>
  <li><a href="/components/card/">Card</a></li>
  <li><a href="/components/split-panel/">Split Panel</a></li>
</ul>

## Storybook

See every state and prop interactively in Storybook: https://storybook.nanatec.co.ke/?path=/docs/components-drawer--docs