Drawer

new

Wait, it's all swipeable? Always has been. A panel that slides in from any edge and swipes away, with a handle, swipe-to-open from the edge, and a bottom that stays above the keyboard.

Demo

Installation

Usage

<script setup lang="ts">
import { Button } from '@/components/ui/button'
import {
  Drawer,
  DrawerBody,
  DrawerClose,
  DrawerContent,
  DrawerDescription,
  DrawerFooter,
  DrawerHeader,
  DrawerTitle,
  DrawerTrigger,
} from '@/components/ui/drawer'
</script>

<template>
  <Drawer>
    <DrawerTrigger as-child>
      <Button>Edit profile</Button>
    </DrawerTrigger>
    <DrawerContent>
      <DrawerHeader>
        <DrawerTitle>Edit profile</DrawerTitle>
        <DrawerDescription>Changes are saved when you press Save.</DrawerDescription>
      </DrawerHeader>
      <DrawerBody>
        <!-- the content -->
      </DrawerBody>
      <DrawerFooter>
        <DrawerClose as-child>
          <Button>Save</Button>
        </DrawerClose>
      </DrawerFooter>
    </DrawerContent>
  </Drawer>
</template>
  • Drawer: holds the state; v-model:open opens it from code
  • DrawerTrigger: opens it
  • DrawerContent: the panel, with an overlay and a drag handle; side picks the edge, bottom by default
  • DrawerHeader, DrawerBody, DrawerFooter: the three parts; the body scrolls when needed
  • DrawerClose: wrap any button in it to make it close the drawer

Under the hood it's a Dialog, so focus, Escape and the overlay work the same. The drawer adds gestures on top.

Drag the panel towards its edge: past halfway or with a quick flick, it closes; otherwise it springs back. If the body is scrolled, it scrolls first; at the top, the drawer moves. A mouse works too, and selecting text never starts a drag.

Examples

Sides

Sides

Scrollable body

Scrollable

Want the thin ScrollArea scrollbar? Put a scroll area in place of DrawerBody, with min-h-0 flex-1. Gestures work the same: it scrolls first, then the drawer moves.

Scroll area

Form

The keyboard shall not pass. On phones, it usually covers bottom panels, but the drawer lifts itself above it and scrolls the focused field into view.

Form

Not dismissible

Not dismissible

Swipe to open

DrawerSwipeArea opens the drawer with a swipe. By default it's an invisible strip along the drawer's edge. Give it a class to move it anywhere or make it visible, like the strip in the demo.

Swipe area

A page with a sheet tucked under its bottom edge.

Controlled

Controlled
closed

Responsive modal

A dialog on desktop, a drawer on phones, one open state. useMediaQuery comes from @vueuse/core. For menus, DrawerMenu does the same.

Responsive

Gesture

Drags start only where they make sense. Got a map or a slider inside? Add data-no-drag, and it keeps its drags for itself. Want dragging only by the handle? Set handle-only. modal: false removes the overlay and keeps the page clickable, and the gestures still work.

Snap points

Like the sheet in a maps app. snap-points lists where the panel can stop, smallest first: 0.5 is half the screen, 320 or "320px" is pixels. Make the panel at least as tall as the largest point (h-[95dvh] in the demo).

It opens at the first point, or at v-model:active-snap-point, and goes back there after closing.

A slow release settles on the nearest point, a quick swipe moves one step, and a hard fling goes all the way. Want one step at a time? Set snap-to-sequential-points. Drag below the smallest point to close, unless dismissible is false. Tapping the handle cycles through the points.

The body scrolls only at the largest point; lower down, every drag moves the panel. The overlay shows only from fade-from-index up (the last point by default), so the page stays readable under a small sheet.

Snap points
at 35%

Scaled page

Wrap the app in DrawerIndent, and the page politely steps back while a drawer is open: it shrinks, rounds its corners and shows black around it (change it with class). It follows your finger too.

<!-- App.vue -->
<template>
  <DrawerIndent>
    <RouterView />
  </DrawerIndent>
</template>

position: sticky keeps working inside. position: fixed doesn't while the page is scaled, so render fixed things through a portal, as the kit's own overlays do.

Indent
Inbox
  • Grace HopperCompiler notes for Monday
  • Alan TuringRe: the imitation game
  • Katherine JohnsonTrajectory figures attached

Nested drawers

Drawers all the way down. Open one from another, and it stacks on top while the ones below step back. Swipe the top one away, and the stack moves forward under your finger.

Nested

From code

Works like opening a dialog from code, with the same service. Put DialogHost inside DrawerIndent, so drawers opened from code step the page back too.

Render DrawerContent and close with useDialogContext(), both imported from the drawer:

<!-- ShareDrawer.vue -->
<script setup lang="ts">
import { Button } from '@/components/ui/button'
import { DrawerContent, DrawerHeader, DrawerTitle, useDialogContext } from '@/components/ui/drawer'

const { close } = useDialogContext<string>()
</script>

<template>
  <DrawerContent>
    <DrawerHeader>
      <DrawerTitle>Share</DrawerTitle>
    </DrawerHeader>
    <Button @click="close('Mail')">Mail</Button>
  </DrawerContent>
</template>

openDrawer(component, props, options) and defineDrawer() work like openDialog and defineDialog. The options are Drawer's props: side, dismissible, handle-only, modal and snap points. A swipe that closes the drawer gives the reason swipe, and while loading is true, a swipe springs back instead of closing.

Programmatic

holiday.jpg is ready to share.

Motion

DurationEasing
Open--transition-duration-medium-4--ease-emphasized-decelerate
Close--transition-duration-short-4--ease-standard-decelerate
Spring back, page scale, stacking--transition-duration-medium-2--ease-standard

While you drag, there's no transition: the panel follows your finger exactly. With reduced motion, it appears and disappears at once, but still follows a drag.

It all runs on the drawer-slide, drawer-overlay-fade and drawer-indent utilities from @kappa-ui/core/tailwind.css.

Using the per-frame variables (--drawer-swipe-movement, --drawer-swipe-progress, --drawer-nested-progress, --drawer-indent-progress)? Read them on the element that has them, not on its children. They don't inherit, for performance.

VariableDefaultDescription
--drawer-sizemeasuredThe panel's size along its axis, in px.
--drawer-swipe-movement0pxOn the panel, how far a drag has moved it towards its edge.
--drawer-swipe-progress0On the panel and the overlay, movement divided by size, from 0 to 1. The overlay fades with it; with snap points it stays 0 on the overlay.
--drawer-snap-offset0pxWhat the active snap point hides below the edge; added to the swipe movement.
--drawer-overlay-opacity1On the overlay, the opacity from fade-from-index, 0 to 1; multiplied with the swipe fade.
--drawer-keyboard-inset0pxWhat the visual viewport lost to the keyboard; a bottom drawer lifts by it.
--drawer-nested0On a drawer, the number of drawers open above it.
--drawer-nested-progress0On a drawer, how far it has stepped back; each drawer above adds up to 1, less while it is swiped away.
--drawer-indent-progress0On the page in DrawerIndent, how far it has stepped back, from 0 to 1; follows the first open drawer.
--drawer-indent-top0pxOn the page, how much of it is above the screen when the indent starts; the scale and clip use the part on screen.
--drawer-indent-bottom0pxOn the page, how much of it is below the screen when the indent starts.

API Reference

Every part except Drawer, which renders no element, accepts class, merged over its own classes with tailwind-merge. On DrawerContent it styles the panel, so h-[85dvh] sets a bottom drawer's height and bg-* replaces its background.

Data attributes

data-slotAttributesDescription
drawer-triggerdata-stateThe element that opens the drawer.
drawer-overlaydata-state, data-swipingThe scrim; fades with the swipe.
drawer-contentdata-state, data-side, data-swiping, data-expanded, data-nested-open, data-nested-swipingThe panel; carries the variables above. data-expanded while it shows its full size, without snap points or at the largest one; data-nested-open while a drawer is open above it, data-nested-swiping while that one is swiped.
drawer-handle—The drag bar; a tap on it closes, or with snap points moves to the next point.
drawer-swipe-areadata-sideThe strip that opens the drawer with a swipe; its gesture is live while the drawer is closed.
drawer-indent—The wrapper around the page; its background shows around the scaled page.
drawer-indent-pagedata-open, data-side, data-swipingThe page. data-open while a modal drawer is open; data-side and data-swiping from the first open drawer, kept until the page has returned.
drawer-header—The title block.
drawer-title—The heading that names the drawer.
drawer-description—The text under the title.
drawer-body—The scrolling middle.
drawer-footer—The actions row.
drawer-close—A button that closes the drawer, including the optional corner one.

Accessibility

The drawer's name comes from its DrawerTitle and its description from its DrawerDescription; always give it a title. When either is missing, the panel renders an empty hidden one, so Reka UI does not warn. The handle is aria-hidden: keyboard users close the drawer with Escape or a button.

KeyAction
Tab / Shift + TabMoves to the next or previous control in the panel, wrapping around inside it.
EscapeCloses the drawer and returns focus to the element that opened it.

Changelog

  1. registry 0.24.1

    35a5371 — No component styles an element through a :has() on its parent or group any more. Chrome restyles the whole subtree of every :has() anchor above a node that is added or removed, once some rule puts :has() away from the element it styles: a page wrapped in one such anchor recalculated every element for each list row it mounted. The Dialog, Drawer and Tour headers, the InputGroup and InputNumber insets, the Combobox clear button, the InputFloating notch, a FieldLabel beside a disabled checkbox or radio, the Rating ring, and the Slider and ScrollArea examples now read their neighbours with ~ or a :has() on the element itself. The InputGroup addons fade through a variable that the group sets. FileUpload, Image, Marquee and DataTable mark the state on an element instead: the hidden input's focus, an ImageError inside, keyboard focus, and the body above pinned bottom rows. scripts/has-selectors.test.ts keeps the pattern out.

    useSwipeSnap no longer flushes styles for an instant move that leaves the offset where it is, such as new points at rest.

  2. core 0.17.1

    35a5371 — No component styles an element through a :has() on its parent or group any more. Chrome restyles the whole subtree of every :has() anchor above a node that is added or removed, once some rule puts :has() away from the element it styles: a page wrapped in one such anchor recalculated every element for each list row it mounted. The Dialog, Drawer and Tour headers, the InputGroup and InputNumber insets, the Combobox clear button, the InputFloating notch, a FieldLabel beside a disabled checkbox or radio, the Rating ring, and the Slider and ScrollArea examples now read their neighbours with ~ or a :has() on the element itself. The InputGroup addons fade through a variable that the group sets. FileUpload, Image, Marquee and DataTable mark the state on an element instead: the hidden input's focus, an ImageError inside, keyboard focus, and the body above pinned bottom rows. scripts/has-selectors.test.ts keeps the pattern out.

    useSwipeSnap no longer flushes styles for an instant move that leaves the offset where it is, such as new points at rest.

  3. registry 0.23.0

    bc6008b — Exits now use the decelerating curve, like entrances. Collapsible, Accordion, the overlay surfaces (Popover, Select, Menu, Tooltip), Drawer, Toast and InnerLoading used to close on --ease-emphasized-accelerate, which holds still for most of its duration and then snaps shut; closing on --ease-standard-decelerate starts at once and settles gently, so the same duration feels faster. The tokens themselves are unchanged.

  4. core 0.17.0

    0107e40 — The scrollbar's space is kept only while an overlay locks scrolling, as Base UI does, instead of on every page. @kappa-ui/core/tailwind.css no longer sets html { scrollbar-gutter: stable }, so a page too short to scroll no longer shows an empty strip along its edge on Windows. Dialog, Drawer, Select, Menu, Popover and DatePicker set scrollbar-gutter: stable on <html> while the page is locked and it would otherwise scroll, and remove it afterwards; a gutter your stylesheet already reserves is left alone. Keep ConfigProvider with :scroll-body="false". Want the old always-on gutter? Add html { scrollbar-gutter: stable; } to your stylesheet.

    bc6008b — Exits now use the decelerating curve, like entrances. Collapsible, Accordion, the overlay surfaces (Popover, Select, Menu, Tooltip), Drawer, Toast and InnerLoading used to close on --ease-emphasized-accelerate, which holds still for most of its duration and then snaps shut; closing on --ease-standard-decelerate starts at once and settles gently, so the same duration feels faster. The tokens themselves are unchanged.

  5. registry 0.22.0

    8ee8861 — DrawerHandle as-child renders its child with the handle's behaviour; the registry part used to drop its slot, so the handle vanished.

    ca08048 — A Dialog (or AlertDialog, or a useConfirm prompt) opened over a Drawer, or a Drawer opened over a Dialog, dims the page once: the lower overlay turns transparent as it already did for a dialog over a dialog.

    a68b4b7 — Toasts stay clickable while a modal Dialog, Drawer or other overlay that blocks outside pointer events is open: a press on a toast's action runs it instead of falling through to the dialog's overlay and closing the dialog.

  6. core 0.16.0

    0b689cc — v-ripple measures its host in the host's own CSS pixels: under a scaled ancestor (transform: scale(), such as a zoomed canvas or the page behind an open DrawerIndent), a wave now starts under the pointer and is sized for the host instead of starting at the scaled point and growing from the shrunken rect. A keyboard wave is centred the same way.

  7. core 0.14.0

    6887534 — A finger drag no longer freezes when a second finger touches the screen: useDrag keeps following the first finger and releases when it lifts, so SwipeViews, useSwipeSnap, Drawer and SwipeActions settle instead of staying stuck mid-drag. A second finger that lands before the drag starts still keeps it from starting. A pen or mouse pressed during a finger drag, or a finger during a pen or mouse drag, no longer starts a second drag on top of the first.

  8. registry 0.9.0

    f3e1bd4 — New AlertDialog: shadcn's parts over Reka UI's AlertDialog on Dialog's window and overlay, with AlertDialogMedia, a sm size, and AlertDialogAction / AlertDialogCancel that take Button's variant, color and size. New confirm item: useConfirm() returns confirm, alert and prompt, which open alert dialogs from code and resolve with a DialogResult; onConfirm holds the dialog with a spinner while it runs and keeps it open if it throws, and prompt validates its value.

    f4d7e8e — ScrollArea's scrollbar carries data-no-drag, so dragging its thumb with a mouse inside a Drawer scrolls instead of moving the drawer.

  9. core 0.8.0

    196be12 — A finger drags a drawer through touch events whenever the device reports touch at the moment of the press (ontouchstart or navigator.maxTouchPoints), as Base UI's Drawer does, instead of only when ontouchstart existed at page load. A swipe from the top of a scrolled body now closes the drawer after DevTools switches on touch emulation. A finger whose scroll reaches the edge mid-gesture hands the gesture to the drawer while the browser still lets its moves be cancelled.

    4b4d53a — A drag no longer re-renders the drawer's content or the page in DrawerIndent: DrawerContent, DrawerOverlay and DrawerIndent write the values that change every frame straight to their elements, and tailwind.css registers --drawer-swipe-movement, --drawer-swipe-progress and the variables derived from them with inherits: false, so a frame restyles one element rather than its subtree. Read --drawer-swipe-movement and --drawer-swipe-progress on the panel or the overlay itself; its children now see 0.

  10. registry 0.8.0

    a455da4 — Drawer: DrawerIndent scales the page behind an open drawer, and a drawer opened from another one stacks on top while the one below steps back.

    154d2f7 — Drawer: openDrawer and defineDrawer open a drawer from code, and @/ui/drawer re-exports useDialogContext for the component it opens.

    63adf67 — Drawer: snap points through snap-points, v-model:active-snap-point, snap-to-sequential-points and fade-from-index; DrawerBody scrolls only at the largest point; a mouse drags the panel from anywhere; the swipe-to-open example shows a visible zone.

    92a9ce3 — Drawer: Drawer, DrawerTrigger, DrawerContent, DrawerOverlay, DrawerHandle, DrawerSwipeArea, DrawerHeader, DrawerTitle, DrawerDescription, DrawerBody, DrawerFooter and DrawerClose over @kappa-ui/core/drawer, shaped like Dialog's parts, on four sides.

  11. core 0.7.0

    92a9ce3 — @kappa-ui/core/drawer: DrawerRoot, DrawerContent, DrawerOverlay, DrawerHandle and DrawerSwipeArea over Reka UI's dialog, with a swipe-to-dismiss gesture on every side, swipe-to-open from the screen edge and a bottom edge that lifts above the virtual keyboard. New modules @kappa-ui/core/drag (useDrag over @use-gesture/vanilla with the drag-start rules) and @kappa-ui/core/virtual-keyboard (useVirtualKeyboardInset). tailwind.css gains drawer-slide and drawer-overlay-fade. @use-gesture/vanilla and @vueuse/core become dependencies. DismissReason gains "swipe".

    a455da4 — DrawerIndent in @kappa-ui/core/drawer: the page element that steps back while a modal drawer is open. Open modal drawers form a stack in the nearest DrawerIndent, or a shared one without it. The page follows the first drawer through --drawer-indent-progress, data-side, data-swiping and the part of it on screen (--drawer-indent-top, --drawer-indent-bottom), kept until its return transition ends, and carries data-open. A drawer content gets --drawer-nested, --drawer-nested-progress, data-nested-open and data-nested-swiping from the drawers above it. tailwind.css adds the drawer-indent utility, and drawer-slide steps a drawer back while others are open above it.

    154d2f7 — openDrawer(component, props?, options?) and defineDrawer(component, { props, keepMounted, ...options }) in @kappa-ui/core/drawer open a drawer from code through the dialog service, with Drawer's props as options. A dialog manager entry can carry a root component, which DialogHost renders in place of Reka's DialogRoot.