# Drawer Primitive

Drawer is a Starwind Runtime primitive in the dialog-native-overlay contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render Drawer anatomy with the Runtime wiring included.
```astro
---
import { Drawer } from "@starwind-ui/astro/drawer";
---

<Drawer.Root>
  <Drawer.Trigger>Open drawer</Drawer.Trigger>
  <Drawer.Backdrop />
  <Drawer.Viewport>
    <Drawer.Popup>
      <Drawer.Title>Drawer title</Drawer.Title>
      <Drawer.Description>Drawer description</Drawer.Description>
      <Drawer.Close>Close</Drawer.Close>
    </Drawer.Popup>
  </Drawer.Viewport>
</Drawer.Root>
```

### React
Use the React primitive adapter when Drawer state participates in React rendering.
```tsx
import { Drawer } from "@starwind-ui/react/drawer";

export function Example() {
  return (
    <Drawer.Root>
      <Drawer.Trigger>Open drawer</Drawer.Trigger>
      <Drawer.Backdrop />
      <Drawer.Viewport>
        <Drawer.Popup>
          <Drawer.Title>Drawer title</Drawer.Title>
          <Drawer.Description>Drawer description</Drawer.Description>
          <Drawer.Close>Close</Drawer.Close>
        </Drawer.Popup>
      </Drawer.Viewport>
    </Drawer.Root>
  );
}
```

### HTML
Render the Drawer data-sw-* contract yourself, then initialize createDrawer.
```html
<div data-sw-drawer>
  <button data-sw-drawer-trigger type="button" aria-haspopup="dialog">Open drawer</button>
  <div data-sw-drawer-backdrop hidden></div>
  <div data-sw-drawer-viewport>
    <dialog data-sw-drawer-popup role="dialog">
      <h2 data-sw-drawer-title>Drawer title</h2>
      <p data-sw-drawer-description>Drawer description</p>
      <button data-sw-drawer-close type="button">Close</button>
    </dialog>
  </div>
</div>

<script type="module">
  import { createDrawer } from "@starwind-ui/runtime/drawer";

  const root = document.querySelector("[data-sw-drawer]");
  if (root) {
    createDrawer(root);
  }
</script>
```

### Vue
Use the Vue 3.5 beta adapter to render Drawer anatomy.
```vue
<script setup lang="ts">
import Drawer from "@starwind-ui/vue/drawer";
</script>

<template>
  <Drawer.Root>
    <Drawer.Trigger>Open drawer</Drawer.Trigger>
    <Drawer.Backdrop />
    <Drawer.Viewport>
      <Drawer.Popup>
        <Drawer.Title>Drawer title</Drawer.Title>
        <Drawer.Description>Drawer description</Drawer.Description>
        <Drawer.Close>Close</Drawer.Close>
      </Drawer.Popup>
    </Drawer.Viewport>
  </Drawer.Root>
</template>
```
## API Reference
### Root
The main element that owns the Drawer Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-drawer` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| open | `boolean` | - | control | Controls whether Drawer is open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| defaultOpen | `boolean` | false | control | Sets whether Drawer starts open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| closeOnEscape | `boolean` | true | option | Closes Drawer when Escape is pressed. | - |
| closeOnOutsideInteract | `boolean` | true | option | Closes Drawer when the user interacts outside it. | - |
| modal | `boolean` | true | option | Makes Drawer behave as a modal overlay. | - |
| onCloseComplete | `(open: boolean, details: DrawerCloseCompleteDetails) => void` | - | callback | Runs after Drawer has finished closing. | - |
| onOpenChange | `(open: boolean, details: DrawerOpenChangeDetails) => void` | - | callback | Runs when Drawer opens or closes. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-drawer` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-default-open` | prop | - | Reflects the default open prop on the Root part. |
| `data-close-on-escape` | prop | - | Reflects the close on escape prop on the Root part. |
| `data-close-on-outside-interact` | prop | - | Reflects the close on outside interact prop on the Root part. |
| `data-modal` | prop | - | Reflects the modal prop on the Root part. |
| `data-state` | state | - | Reflects the current state on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| open | `boolean` | open | defaultOpen | `data-default-open` | `getOpen` | `setOpen` | Tracks whether Drawer is open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| openChange | onOpenChange | starwind:open-change | open: `boolean` | DrawerOpenChangeDetails | before-state-commit | Yes | Fires when Drawer opens or closes. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
| closeComplete | onCloseComplete | starwind:close-complete | open: `boolean` | DrawerCloseCompleteDetails | after-state-commit | No | Fires after Drawer has finished closing. | - |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setOpen` | state: open | emit: false | Yes | Opens or closes Drawer from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-drawer`, `data-default-open`, `data-close-on-escape`, `data-close-on-outside-interact`, `data-modal`, `data-state` | The drawer root needs default-open, dismissal, modality, and initial state markers before hydration. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | No |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Trigger
The control that opens, closes, or targets the Drawer content.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-drawer-trigger` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| targetId | `string` | - | attribute | Targets a specific root element by id. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-drawer-trigger` | runtime | - | Marks the Trigger part so Starwind Runtime can find it. |
| `data-sw-drawer-target-id` | prop | - | Reflects the sw drawer target id prop on the Trigger part. |
| `data-state` | state | - | Reflects the current state on the Trigger part. |
#### Refs
| Part | Public |
| --- | --- |
| trigger | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-drawer-trigger`, `type`, `aria-haspopup`, `data-sw-drawer-target-id`, `data-state` | Triggers need button semantics, dialog affordances, and initial closed state before activation listeners attach. |

### Portal
Moves Drawer overlay content to the document body when needed.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-drawer-portal` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-drawer-portal` | runtime | - | Marks the Portal part so Starwind Runtime can find it. |
| `data-container` | prop | - | Reflects the container prop on the Portal part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Portal part. |
| `data-sw-portal-placement` | constant | `runtime` | Identifies Portal metadata for styling and selectors. |
| `data-placement` | runtime | - | Marks the Portal part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| portal | Yes |

### Backdrop
The backdrop shown behind the Drawer overlay.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-drawer-backdrop` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-drawer-backdrop` | runtime | - | Marks the Backdrop part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Backdrop part. |
#### Refs
| Part | Public |
| --- | --- |
| backdrop | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-drawer-backdrop`, `data-state`, `hidden` | The backdrop starts hidden and receives runtime-owned open/close visibility. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | Yes |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Viewport
The visible viewport for Drawer content.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-drawer-viewport` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-drawer-viewport` | runtime | - | Marks the Viewport part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| viewport | Yes |

### Popup
The floating content container for Drawer.
| Fact | Value |
| --- | --- |
| Default element | `dialog` |
| Discovery hook | `data-sw-drawer-popup` |
| Role | `dialog` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| side | `"top" \| "right" \| "bottom" \| "left"` | "right" | option | Sets the preferred side for Drawer content. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-drawer-popup` | runtime | - | Marks the Popup part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Popup part. |
| `data-side` | prop | - | Reflects the side prop on the Popup part. |
#### Refs
| Part | Public |
| --- | --- |
| popup | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-drawer-popup`, `data-state`, `data-side` | The native drawer popup starts closed with dialog semantics and side placement before runtime normalization maps it onto the Dialog controller. |

### Title
The accessible title for Drawer.
| Fact | Value |
| --- | --- |
| Default element | `h2` |
| Discovery hook | `data-sw-drawer-title` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-drawer-title` | runtime | - | Marks the Title part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| title | Yes |

### Description
Supporting description text for Drawer.
| Fact | Value |
| --- | --- |
| Default element | `p` |
| Discovery hook | `data-sw-drawer-description` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-drawer-description` | runtime | - | Marks the Description part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| description | Yes |

### Close
A control that closes Drawer.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-drawer-close` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-drawer-close` | runtime | - | Marks the Close part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| close | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-drawer-close`, `type` | Close controls need button semantics before runtime listeners attach. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createDrawer`](/docs/runtime/#create-drawer) |
| Import | `@starwind-ui/runtime/drawer` |
| Root part | root |
| Option props | closeOnEscape, closeOnOutsideInteract, defaultOpen, modal, onCloseComplete, onOpenChange, open |
| Option lifecycles | closeOnEscape: constructor-only, closeOnOutsideInteract: constructor-only, defaultOpen: constructor-only, modal: constructor-only, onCloseComplete: constructor-only, onOpenChange: constructor-only, open: setter-backed |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Sheet](/docs/components/sheet/) | Renamed Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/drawer` | `createDrawer` |
| Astro Primitive | `@starwind-ui/astro/drawer` | `Drawer`, `DrawerRoot`, `DrawerTrigger`, `DrawerPortal`, `DrawerBackdrop`, `DrawerViewport`, `DrawerPopup`, `DrawerTitle`, `DrawerDescription`, `DrawerClose` |
| React Primitive | `@starwind-ui/react/drawer` | `Drawer`, `DrawerRoot`, `DrawerTrigger`, `DrawerPortal`, `DrawerBackdrop`, `DrawerViewport`, `DrawerPopup`, `DrawerTitle`, `DrawerDescription`, `DrawerClose` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Drawer` |
| runtime-factory | `createDrawer` |
| part | `Drawer.Root` |
| part | `Drawer.Trigger` |
| part | `Drawer.Portal` |
| part | `Drawer.Backdrop` |
| part | `Drawer.Viewport` |
| part | `Drawer.Popup` |
| part | `Drawer.Title` |
| part | `Drawer.Description` |
| part | `Drawer.Close` |
## Changelog
### v1.1.1
- Removed obsolete private-release warnings from generated Vue adapters and normalized the resulting blank line in vendored Primitive indexes.
### v1.1.0
- Added portable Portal container and disabled controls, with deterministic framework and Runtime placement reporting for nested floating content.
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.1
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
- Kept generated React state-change callbacks and DOM events cancelable until the Runtime accepts the proposed state, then synchronized rendered state.
### v0.1.0
- Introduced sliding dialog behavior with modal state, focus management, dismissal, and panel presence.