On this page

Drawer Primitive

Drawer is a Starwind Runtime primitive in the dialog-native-overlay contract family. Astro, React, Vue, and Svelte components use the same underlying interactions. Each framework has its own way to read and update state. See the examples and your installed package’s types for the available props and events. Plain HTML uses DOM events and Runtime methods.

Anatomy

Use the Astro primitive adapter to render Drawer anatomy with the Runtime wiring included.

---
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>

Use the React primitive adapter when Drawer state participates in React rendering.

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>
  );
}

Use the Vue components to build Drawer.

<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>

Render the Drawer data-sw-* contract yourself, then initialize createDrawer.

<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>

API Reference

Root

The main element that owns the Drawer Runtime instance.

Default element: div
Discovery hook: data-sw-drawer
Role: -

Props

Prop Type Default

open boolean -

Description

Controls whether Drawer is open.

Kind

control

Targets

root

Full type

boolean

React

Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.

open
defaultOpen
onOpenChange

Astro

Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.

open
defaultOpen
starwind:open-change
setOpen

Runtime / HTML

Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates.

data-default-open
starwind:open-change
setOpen

defaultOpen boolean false

Description

Sets whether Drawer starts open.

Kind

control

Targets

root

Full type

boolean

React

Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.

open
defaultOpen
onOpenChange

Astro

Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.

open
defaultOpen
starwind:open-change
setOpen

Runtime / HTML

Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates.

data-default-open
starwind:open-change
setOpen

closeOnEscape boolean true

Description: Closes Drawer when Escape is pressed.
Kind: option
Targets: -
Full type: boolean

closeOnOutsideInteract boolean true

Description: Closes Drawer when the user interacts outside it.
Kind: option
Targets: -
Full type: boolean

modal boolean true

Description: Makes Drawer behave as a modal overlay.
Kind: option
Targets: -
Full type: boolean

onCloseComplete (open: boolean, details: DrawerCloseCompleteDetails) => void -

Description: Runs after Drawer has finished closing.
Kind: callback
Targets: -
Full type: (open: boolean, details: DrawerCloseCompleteDetails) => void

onOpenChange (open: boolean, details: DrawerOpenChangeDetails) => void -

Description

Runs when Drawer opens or closes.

Kind

callback

Targets

Full type

(open: boolean, details: DrawerOpenChangeDetails) => void

React

Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.

open
defaultOpen
onOpenChange

Astro

Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.

open
defaultOpen
starwind:open-change
setOpen

Runtime / HTML

Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates.

data-default-open
starwind:open-change
setOpen

Events

Event Callback Value

openChange onOpenChange open: boolean

Description

Fires when Drawer opens or closes.

DOM event

starwind:open-change

Details type

DrawerOpenChangeDetails

Timing

before-state-commit

Cancelable

Yes

Cancellation sequence

Check internal eligibility and intent.
Create one details object for the proposal.
Call the Runtime callback with the details object when the controller exposes one.
Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.
Read details.isCanceled, including cancellation caused by preventDefault().
Apply the accepted state.
Notify Runtime subscribers and other accepted-only observers.

closeComplete onCloseComplete open: boolean

Description: Fires after Drawer has finished closing.
DOM event: starwind:close-complete
Details type: DrawerCloseCompleteDetails
Timing: after-state-commit
Cancelable: No

State

State Type Props

open boolean open / defaultOpen

Description

Tracks whether Drawer is open.

Initial attribute

data-default-open

Runtime getter

getOpen

Runtime setter

setOpen

React

Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.

open
defaultOpen
onOpenChange

Astro

Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.

open
defaultOpen
starwind:open-change
setOpen

Runtime / HTML

Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates.

data-default-open
starwind:open-change
setOpen

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-drawer - Marks the Root part so Starwind Runtime can find it.

State

Attribute Value Description

data-state - Reflects the current state on the Root part.

Metadata

Attribute Value Description

data-default-open - Reflects the default open prop on the Root part.

data-close-on-escape - Reflects the close on escape prop on the Root part.

data-close-on-outside-interact - Reflects the close on outside interact prop on the Root part.

data-modal - Reflects the modal prop on the Root part.

Trigger

The control that opens, closes, or targets the Drawer content.

Default element: button
Discovery hook: data-sw-drawer-trigger
Role: -

Props

Prop Type Default

asChild boolean false

Description: Merges behavior onto your child element instead of rendering the default Trigger element.
Kind: rendering
Targets: trigger, close
Full type: boolean

targetId string -

Description: Targets a specific root element by id.
Kind: attribute
Targets: trigger
Full type: string

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-drawer-trigger - Marks the Trigger part so Starwind Runtime can find it.

State

Attribute Value Description

data-state - Reflects the current state on the Trigger part.

Metadata

Attribute Value Description

data-sw-drawer-target-id - Reflects the sw drawer target id prop on the Trigger part.

Portal

Moves Drawer overlay content to the document body when needed.

Default element: div
Discovery hook: data-sw-drawer-portal
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-drawer-portal - Marks the Portal part so Starwind Runtime can find it.

data-placement - Marks the Portal part so Starwind Runtime can find it.

Metadata

Attribute Value Description

data-container - Reflects the container prop on the Portal part.

data-disabled - Reflects the disabled prop on the Portal part.

data-sw-portal-placement runtime Identifies Portal metadata for styling and selectors.

Backdrop

The backdrop shown behind the Drawer overlay.

Default element: div
Discovery hook: data-sw-drawer-backdrop
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-drawer-backdrop - Marks the Backdrop part so Starwind Runtime can find it.

State

Attribute Value Description

data-state - Reflects the current state on the Backdrop part.

Viewport

The visible viewport for Drawer content.

Default element: div
Discovery hook: data-sw-drawer-viewport
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-drawer-viewport - Marks the Viewport part so Starwind Runtime can find it.

The floating content container for Drawer.

Default element: dialog
Discovery hook: data-sw-drawer-popup
Role: dialog

Props

Prop Type Default

side "top" | "right" | "bottom" | "left" "right"

Description: Sets the preferred side for Drawer content.
Kind: option
Targets: popup
Full type: "top" | "right" | "bottom" | "left"

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-drawer-popup - Marks the Popup part so Starwind Runtime can find it.

State

Attribute Value Description

data-state - Reflects the current state on the Popup part.

Metadata

Attribute Value Description

data-side - Reflects the side prop on the Popup part.

Title

The accessible title for Drawer.

Default element: h2
Discovery hook: data-sw-drawer-title
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-drawer-title - Marks the Title part so Starwind Runtime can find it.

Description

Supporting description text for Drawer.

Default element: p
Discovery hook: data-sw-drawer-description
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-drawer-description - Marks the Description part so Starwind Runtime can find it.

Close

A control that closes Drawer.

Default element: button
Discovery hook: data-sw-drawer-close
Role: -

Props

Prop Type Default

asChild boolean false

Description: Merges behavior onto your child element instead of rendering the default Close element.
Kind: rendering
Targets: trigger, close
Full type: boolean

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-drawer-close - Marks the Close part so Starwind Runtime can find it.

Runtime API

Factory: createDrawer
Import: @starwind-ui/runtime/drawer
Root hook: root data-sw-drawer
Option props: closeOnEscape, closeOnOutsideInteract, defaultOpen, modal, onCloseComplete, onOpenChange, open

Option Lifecycles

Option	Lifecycle
closeOnEscape	constructor-only
closeOnOutsideInteract	constructor-only
defaultOpen	constructor-only
modal	constructor-only
onCloseComplete	constructor-only
onOpenChange	constructor-only
open	setter-backed

Runtime Setters

Method Target Description

setOpen state: open Opens or closes Drawer from Runtime code.

Component Relationship

Sheet Renamed primitive

Changelog

View version history v1.2.0 6 releases

v1.2.0

Vue Drawer keeps its current open state when a change is canceled and responds to later open or close requests from your app.
Trigger and close buttons added after the drawer mounts now work without reopening it.
Reduced background work when a React page uses multiple menus, tooltips, or other portals.
Added `asChild` support to React and Vue controls so you can use your own elements without an extra wrapper.
Fixed nested Svelte overlays inside a dialog appearing behind their parent or failing to receive clicks.
Reduced background work when a Vue page uses multiple menus, tooltips, or other portals.
Fixed nested overlays appearing behind their parent in Vue and Svelte. Overlays can now render under the document body; if custom CSS or DOM queries require them to stay inside a parent, set a portal container or add `data-floating-root` to that parent.
Fixed React 18 retaining removed popup elements when the parent component stays mounted.
Updated the shared setup file included with the Astro Primitive. Its public API and behavior are unchanged.

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.

Layer Metadata

Drawer Primitive uses createDrawer. Styled components: Sheet.

primitive Drawer Primitive Drawer Primitive uses createDrawer. Styled components: Sheet. Runtime primitive Primitive adapter Astro Primitive adapters React Primitive adapters drawer Drawer Dialog Native Overlay Native dialog-backed overlays with runtime-owned dismissal and presence. /docs/primitives/drawer/ createDrawer @starwind-ui/runtime/drawer /docs/runtime/#create-drawer root closeOnEscape closeOnOutsideInteract defaultOpen modal onCloseComplete onOpenChange open raw-html astro react solid svelte vue HTML Astro React Solid Svelte Vue Raw HTML Render the Drawer data-sw-* contract yourself, then initialize createDrawer. html Use the Astro primitive adapter to render Drawer anatomy with the Runtime wiring included. Use the React primitive adapter when Drawer state participates in React rendering. tsx Use the Vue components to build Drawer. div data-sw-drawer boolean Controls whether Drawer is open. Sets whether Drawer starts open. Closes Drawer when Escape is pressed. Closes Drawer when the user interacts outside it. Makes Drawer behave as a modal overlay. (open: boolean, details: DrawerCloseCompleteDetails) => void DrawerCloseCompleteDetails Runs after Drawer has finished closing. (open: boolean, details: DrawerOpenChangeDetails) => void DrawerOpenChangeDetails Runs when Drawer opens or closes. 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 Reflects the close on escape prop on the Root part. data-close-on-outside-interact Reflects the close on outside interact prop on the Root part. data-modal Reflects the modal prop on the Root part. data-state state Reflects the current state on the Root part. getOpen setOpen openChange starwind:open-change closeComplete starwind:close-complete trigger button data-sw-drawer-trigger asChild Merges behavior onto your child element instead of rendering the default Trigger element. targetId string Targets a specific root element by id. Marks the Trigger part so Starwind Runtime can find it. data-sw-drawer-target-id Reflects the sw drawer target id prop on the Trigger part. Reflects the current state on the Trigger part. portal data-sw-drawer-portal Marks the Portal part so Starwind Runtime can find it. data-container Reflects the container prop on the Portal part. data-disabled Reflects the disabled prop on the Portal part. data-sw-portal-placement constant Identifies Portal metadata for styling and selectors. data-placement backdrop data-sw-drawer-backdrop Marks the Backdrop part so Starwind Runtime can find it. Reflects the current state on the Backdrop part. viewport data-sw-drawer-viewport Marks the Viewport part so Starwind Runtime can find it. popup dialog data-sw-drawer-popup side "top" | "right" | "bottom" | "left" Sets the preferred side for Drawer content. Marks the Popup part so Starwind Runtime can find it. Reflects the current state on the Popup part. data-side Reflects the side prop on the Popup part. title h2 data-sw-drawer-title Marks the Title part so Starwind Runtime can find it. description p data-sw-drawer-description Marks the Description part so Starwind Runtime can find it. close data-sw-drawer-close Merges behavior onto your child element instead of rendering the default Close element. Marks the Close part so Starwind Runtime can find it. Root Trigger type aria-haspopup Portal Backdrop hidden Viewport Popup Title Description Close @starwind-ui/astro @starwind-ui/astro/drawer Render static drawer anatomy and self-initialize; runtime normalizes Drawer parts onto the shared Dialog controller. @starwind-ui/react @starwind-ui/react/drawer Bridge controlled open state through setOpen, wire onOpenChange through the factory for cancellable before-commit callbacks, pass close completion through the factory, and recreate on constructor-only option changes. @starwind-ui/vue @starwind-ui/vue/drawer @starwind-ui/svelte @starwind-ui/svelte/drawer sheet Sheet /docs/components/sheet/ Renamed primitive renamed-primitive The styled docs use Sheet while the behavior primitive is drawer. Styled component Sheet

Drawer Primitive

Anatomy

API Reference

Root

Props

Events

State

Data Attributes

Runtime hooks

State

Metadata

Trigger

Props

Data Attributes

Runtime hooks

State

Metadata

Portal

Data Attributes

Runtime hooks

Metadata

Backdrop

Data Attributes

Runtime hooks

State

Viewport

Data Attributes

Runtime hooks

Popup

Props

Data Attributes

Runtime hooks

State

Metadata

Title

Data Attributes

Runtime hooks

Description

Data Attributes

Runtime hooks

Close

Props

Data Attributes

Runtime hooks

Runtime API

Option Lifecycles

Runtime Setters

Related Styled Components

Changelog

v1.2.0

v1.1.1

v1.1.0

v1.0.0

v0.1.1

v0.1.0