Drawer

A panel that slides in from the edge of the screen. The trigger and close match Button. The popup has no stroke, and the open edge is rounded. The title is Light and the description is Regular.

Usage guidelines

• Drawer extends Dialog. It adds gesture support, snap points, and indent effects. If you don’t need those, use Dialog. A panel that slides in from the edge and doesn’t need gestures is a positioned Dialog.

Anatomy

<UiDrawerProvider>
  <UiDrawerIndentBackground />
  <UiDrawerIndent>
    <UiDrawerRoot>
      <UiDrawerTrigger />
      <UiDrawerSwipeArea />
      <UiDrawerPortal>
        <UiDrawerBackdrop />
        <UiDrawerViewport>
          <UiDrawerPopup>
            <UiDrawerContent>
              <UiDrawerTitle />
              <UiDrawerDescription />
              <UiDrawerClose />
            </UiDrawerContent>
          </UiDrawerPopup>
        </UiDrawerViewport>
      </UiDrawerPortal>
    </UiDrawerRoot>
  </UiDrawerIndent>
</UiDrawerProvider>

Drawer supports swipe gestures to dismiss. Set swipeDirection to control which direction dismisses the drawer. UiDrawerContent allows text selection of its children without swipe interference when using a mouse. Add data-swipe-ignore to a descendant to skip swipe dismissal for all input types.

Use UiDrawerVirtualKeyboardProvider when a bottom sheet contains form fields and you want the sheet to react to software keyboards. Drawers without this provider are unaffected.

No drop-shadow and no border. The open edge is rounded.

Examples

State

By default, Drawer is an uncontrolled component that manages its own state.

<UiDrawerRoot>
  <UiDrawerTrigger>Open</UiDrawerTrigger>
  <UiDrawerPortal>
    <UiDrawerViewport>
      <UiDrawerPopup>
        <UiDrawerContent>
          <UiDrawerTitle>Example drawer</UiDrawerTitle>
          <UiDrawerClose>Close</UiDrawerClose>
        </UiDrawerContent>
      </UiDrawerPopup>
    </UiDrawerViewport>
  </UiDrawerPortal>
</UiDrawerRoot>

Use open / v-model:open if you need to access or control the state. For example, close it after a form submits, or open it from another place in the app.

<script setup>
const open = ref(false)
</script>

<template>
  <UiDrawerRoot v-model:open="open" swipe-direction="right">
    <UiDrawerTrigger>Open</UiDrawerTrigger>
    …
  </UiDrawerRoot>
</template>

Position

Positioning is handled by your styles. swipeDirection defaults to "down" for bottom sheets. Use "up", "left", or "right" for other drawer positions. The hero demo above is a right side sheet (swipeDirection="right"). This example is the default bottom sheet.

<UiDrawerRoot swipe-direction="right">

Nested drawers

You can nest drawers within one another. Use [data-nested-drawer-open] and var(--nested-drawers) to style the parent. Child backdrops are not rendered, so the parent stays visible behind the one on top. The parent popup scales with calc(1 - 0.05 * var(--nested-drawers)).

This demo stacks nested drawers so the frontmost sheet stays anchored to the bottom while the ones behind it are scaled down.

Snap points

Use snapPoints to snap a bottom sheet to preset heights. Numbers between 0 and 1 represent fractions of the viewport height, and numbers greater than 1 are treated as pixel values. String values support px and rem units (for example, '148px' or '30rem').

const snapPoints = ['148px', 1]

<UiDrawerRoot
  :snap-points="snapPoints"
  v-model:snap-point="snapPoint"
>

Apply the snap point offset in your styles when using vertical drawers:

.popup {
  transform: translateY(
    calc(var(--drawer-snap-point-offset) + var(--drawer-swipe-movement-y))
  );
}

By default, the drawer can skip snap points when swiping quickly. Set snapToSequentialPoints so drag distance (not velocity) chooses the next point.

Virtual keyboard aware

Wrap a bottom sheet in UiDrawerVirtualKeyboardProvider to make it react to software keyboards when it contains form controls. The provider sets --drawer-keyboard-inset from visualViewport.

• Keep the popup frame stable: place header and footer content outside a scrollable body.
• Lift a pinned footer input with padding-bottom: var(--drawer-keyboard-inset, 0px). Always include the 0px fallback — the variable is only set while a keyboard is aligned.

<UiDrawerRoot>
  <UiDrawerVirtualKeyboardProvider>
    …
  </UiDrawerVirtualKeyboardProvider>
</UiDrawerRoot>

Indent effect

Scale the background down when any drawer opens by wrapping the tree in UiDrawerProvider and placing UiDrawerIndentBackground + UiDrawerIndent around the page. Any UiDrawerRoot within the provider notifies it when it opens, which activates the indent parts ([data-active]). Portal into the framed container with to so the overlay is clipped to the demo.

Non-modal

Set modal={false} (:modal="false") to opt out of focus trapping and page scroll lock. Combine with disablePointerDismissal to keep the drawer open on outside clicks. There is no backdrop; Close, Escape, or swipe still dismiss.

Mobile navigation

You can build a full-screen mobile navigation sheet using Drawer parts, including flick-to-dismiss from the top. Scroll Area keeps a long component list inside the sheet.

Swipe to open

Place UiDrawerSwipeArea along the edge of the viewport to enable swipe-to-open. The swipe direction defaults to the opposite of Root swipeDirection.

Close confirmation

Nest an Alert Dialog inside a controlled Drawer. If the parent would close while the textarea has text, keep the drawer open and show the alert instead. Shown on backdrop click, Escape, Close, or a dismiss swipe.

Action sheet with separate destructive action

An action sheet with a grouped list of actions plus a separate destructive action. Filled actions use .cta / data-cta — never $red.

Detached triggers

For a one-off, put UiDrawerTrigger inside Root. When that is impractical, create a handle with createDrawerHandle() and pass it to both the trigger and the root.

<script setup>
import { createDrawerHandle } from '~/lib/ui/drawer'

const demoDrawer = createDrawerHandle<{ title: string }>()
</script>

<template>
  <UiDrawerTrigger :handle="demoDrawer" :payload="{ title: 'Profile' }">
    Profile
  </UiDrawerTrigger>
  <UiDrawerRoot v-slot="{ payload }" :handle="demoDrawer">
    …
  </UiDrawerRoot>
</template>

The drawer can render different content depending on which trigger opened it. Pass payload on the trigger and read it from Root’s default slot.

Stacking and animations

Use CSS transitions to animate opening, closing, swipe, and nested stacking. data-starting-style is applied when a drawer starts to open, and data-ending-style when it starts to close.

--nested-drawers is the stack depth. The frontmost drawer has index 0.

.popup {
  --stack-step: 0.05;
  --stack-scale: calc(1 - (var(--nested-drawers) * var(--stack-step)));
  transform: translateY(var(--drawer-swipe-movement-y)) scale(var(--stack-scale));
}

data-nested-drawer-open marks drawers behind the frontmost one. Pair it with data-nested-drawer-swiping to show parent content again while the child is being swiped.

.content {
  transition: opacity 300ms;
}

.popup[data-nested-drawer-open] .content {
  opacity: 0;
}

.popup[data-nested-drawer-open][data-nested-drawer-swiping] .content {
  opacity: 1;
}

--drawer-swipe-movement-x, --drawer-swipe-movement-y, and --drawer-snap-point-offset offset the popup while dragging. --drawer-swipe-progress fades the backdrop; --drawer-swipe-strength can scale the release duration.

.backdrop {
  --backdrop-opacity: 0.2;
  opacity: calc(var(--backdrop-opacity) * (1 - var(--drawer-swipe-progress)));
}

.popup[data-ending-style][data-swipe-direction='right'] {
  transform: translateX(100%);
}

.popup[data-ending-style][data-swipe-direction='down'] {
  transform: translateY(100%);
}

The nested-drawers demo above uses this stacking.

API reference

Root

Groups all parts of the drawer. Renders nothing of its own. Default slot receives { payload, triggerId }.

Provider

Coordinates indent / background effects for every drawer under it. Renders nothing of its own.

IndentBackground

Layer behind UiDrawerIndent. Receives [data-active] while any descendant drawer is open.

Indent

Scales its children while a descendant drawer is open ([data-active], --drawer-swipe-progress).

Trigger

Button that opens the drawer. Renders a <button>.

SwipeArea

Edge hit target that opens the drawer when dragged.

VirtualKeyboardProvider

Watches visualViewport and exposes --drawer-keyboard-inset (and keyboardInset on Root) while a software keyboard is open.

Portal

Teleports to body while the overlay is present (useCssPresence). Pass to to portal into a container (indent / swipe demos).

Backdrop

Covers the viewport. Click dismisses unless Root disablePointerDismissal is set. Nested drawers skip rendering the child backdrop unless forceRender is set. Opacity is 0.2 × (1 - --drawer-swipe-progress).

Viewport

Pins the popup to the swipe edge.

Popup

role="dialog". Escape closes. Focus stays inside until close when modal is true. Enter and leave use data-starting-style / data-ending-style (450ms cubic-bezier(0.32, 0.72, 0, 1)). Drag in the swipe direction to dismiss. No animation library. No drop-shadow.

Content

Scrollable body. Mark a child with data-swipe-ignore to skip swipe there. Fades out when [data-nested-drawer-open] unless [data-nested-drawer-swiping].

Title

Heading that labels the drawer. Renders an <h2>.

Description

Supporting text. Renders a <p>.

Close

Button that sets open to false. Add class="cta" for a filled action.

createDrawerHandle

Creates a handle that connects UiDrawerRoot with detached UiDrawerTrigger components.

const handle = createDrawerHandle<{ title: string }>()
handle.show({ title: 'Profile' }, 'drawer-trigger-1')
handle.hide()