Drawer

The drawer is a swipeable panel that slides in from a screen edge and rests at configurable snap points. Use it for mobile-style bottom sheets, multi-height panels like a music player, or any surface a user drags between heights. For a plain slide-in panel without snap points or drag gestures, use Sheet instead.

Preview

Installation

npx shadcn@latest add @cubby-ui/drawer

Usage

import {
  Drawer,
  DrawerClose,
  DrawerContent,
  DrawerDescription,
  DrawerFooter,
  DrawerHandle,
  DrawerHeader,
  DrawerTitle,
  DrawerTrigger,
} from "@/components/ui/cubby-ui/drawer";

<Drawer>
  <DrawerTrigger />
  <DrawerContent>
    <DrawerHandle />
    <DrawerHeader>
      <DrawerTitle />
      <DrawerDescription />
    </DrawerHeader>
    <DrawerFooter>
      <DrawerClose />
    </DrawerFooter>
  </DrawerContent>
</Drawer>

Composition

Drawer
├── DrawerTrigger
└── DrawerContent
    ├── DrawerHandle
    ├── DrawerHeader
    │   ├── DrawerTitle
    │   └── DrawerDescription
    ├── DrawerBody
    └── DrawerFooter
        └── DrawerClose

DrawerContent composes the portal, backdrop, viewport, and popup. Use DrawerBody for scrollable content that cooperates with swipe gestures.

Examples

Controlled

Use open and onOpenChange to drive the drawer's open state externally.

Directions

Use direction to choose which edge the drawer slides in from.

Snap Points

Use snapPoints to let the drawer rest at multiple heights.

Pixel-Based Snap Points

Pass pixel strings in snapPoints for fixed heights that ignore content size.

Sequential Snap Points

Set sequentialSnap to stop at each snap point instead of skipping them on fast swipes.

Floating Variant

Use variant="floating" for an inset, modal-like panel with rounded corners and shadow.

Music Player

Combine snap points with --drawer-snap-progress for progressive disclosure: mini player, expanded controls, and full queue.

Scrollable Content

Use DrawerBody for scrollable content that cooperates with swipe gestures.

With Form

Place form fields inside DrawerBody, with actions in DrawerFooter.

Inset Footer

Set footerVariant="inset" on DrawerContent for a separated footer with a muted background and top border.

Sticky Footer

Add className="sticky bottom-0" to DrawerFooter to pin it as the drawer is dragged down.

Nested

Open a drawer from inside another; the parent scales down and dims behind the nested drawer.

Non-Modal

Use modal to control focus trapping and page interaction.

Accessibility

Include a DrawerTitle (and ideally a DrawerDescription) inside every DrawerContent so the dialog is named for assistive technology. When the modal drawer opens, focus moves into it and is trapped until it closes; modal="trap-focus" keeps the trap while leaving the page interactive, and modal={false} removes the trap entirely. DrawerHandle is a real button labeled "Close drawer" by default; set preventClose to relabel it "Drawer handle" when it should not dismiss.

API Reference

The Drawer component is built on top of Base UI's Dialog. All Base UI props are supported. The documentation below only covers custom props specific to our implementation.

For the complete Base UI API, see the Base UI Dialog documentation.

Props

Drawer

Root component that manages drawer state and provides context to child components. Wraps Base UI's Dialog.Root.

DrawerContent

Main drawer container with swipe gesture handling and positioning. Composes Dialog.Portal, Dialog.Backdrop, Dialog.Viewport, and Dialog.Popup. Props are forwarded to Dialog.Popup.

DrawerBody

Scrollable content area with adaptive padding based on surrounding elements. Wraps ScrollArea.

DrawerHandle

Visual drag indicator that doubles as a close button. Automatically adjusts orientation based on drawer direction.

Components

Nested Scrollable Content

Use DrawerBody for scrollable content inside the drawer. The component handles overflow automatically and adapts its padding based on surrounding elements (header, footer).

<DrawerContent>
  <DrawerHandle />
  <DrawerHeader>
    <DrawerTitle>Long List</DrawerTitle>
  </DrawerHeader>
  <DrawerBody>{/* Your scrollable content */}</DrawerBody>
  <DrawerFooter>
    <DrawerClose render={<Button />}>Done</DrawerClose>
  </DrawerFooter>
</DrawerContent>

Animating Content Based on Snap Position

The drawer exposes a --drawer-snap-progress CSS custom property that animates from 0 (first snap) to 1 (last snap) as the drawer moves between snap points. This works in all browsers:

• Chrome 115+: GPU-accelerated CSS scroll-driven animation (no React re-renders)
• Other browsers: JavaScript fallback sets the variable automatically

Using the CSS Variable

Use --drawer-snap-progress directly in your styles for crossfade effects:

<Drawer snapPoints={["92px", 1]}>
  <DrawerTrigger>Open</DrawerTrigger>
  <DrawerContent>
    {/* Mini player fades out as drawer expands */}
    <div style={{ opacity: "calc(1 - var(--drawer-snap-progress, 0))" }}>
      Mini Player
    </div>
    {/* Full player fades in as drawer expands */}
    <div style={{ opacity: "var(--drawer-snap-progress, 0)" }}>
      Full Player
    </div>
  </DrawerContent>
</Drawer>

Or with Tailwind's arbitrary value syntax:

<div className="opacity-(calc(1-var(--drawer-snap-progress,0)))">Mini Player</div>
<div className="opacity-(--drawer-snap-progress,0)">Full Player</div>

Conditional Logic with Render Props

CSS variables work great for visual properties like opacity, but some properties like pointer-events need conditional logic. Use the render prop pattern for these:

<Drawer snapPoints={["92px", 1]}>
  {({ snapProgress }) => (
    <DrawerContent>
      {/* Opacity via CSS variable, pointer-events via JS */}
      <div
        style={{
          opacity: "calc(1 - var(--drawer-snap-progress, 0))",
          pointerEvents: snapProgress > 0.7 ? "none" : "auto",
        }}
      >
        Mini Player
      </div>
      <div
        style={{
          opacity: "var(--drawer-snap-progress, 0)",
          pointerEvents: snapProgress < 0.3 ? "none" : "auto",
        }}
      >
        Full Player
      </div>
    </DrawerContent>
  )}
</Drawer>

Render Prop Values