Drawer

A modal bottom sheet that slides up from the bottom edge and is dismissed by dragging it down, from @clerk/headless. It is a headless primitive: it supplies open state, portalling, an overlay surface, a scroll-locked viewport, focus management, dismissal (drag / outside press / Escape), optional snap points, virtual-keyboard awareness, nesting, and ARIA wiring, but ships no styles — you bring your own CSS by targeting the data-* state attributes each part emits and composing the raw --cl-drawer-* custom properties it writes. It reuses the same Floating UI infrastructure as Dialog with a hand-rolled drag engine layered on top; prefer Dialog for centered modals with no drag.

Example

The demo below is intentionally unstyled — it renders the raw primitive so you can see its behavior and ARIA wiring. Open it, then drag the sheet down, press Escape, or click outside the popup to dismiss.

Usage

import { Drawer } from '@clerk/headless/drawer';

<Drawer.Root>
  <Drawer.Trigger>Open</Drawer.Trigger>
  <Drawer.Portal>
    <Drawer.Backdrop />
    <Drawer.Viewport>
      <Drawer.Popup>
        <Drawer.Handle />
        <Drawer.Title>Sheet title</Drawer.Title>
        <Drawer.Description>Optional description.</Drawer.Description>
        <p>Sheet content.</p>
        <Drawer.Close>Close</Drawer.Close>
      </Drawer.Popup>
    </Drawer.Viewport>
  </Drawer.Portal>
</Drawer.Root>;

Controlled

const [open, setOpen] = useState(false);

<Drawer.Root
  open={open}
  onOpenChange={setOpen}
>
  {/* trigger + portal */}
</Drawer.Root>;

Detached trigger

A trigger rendered outside Drawer.Root can drive it through a shared handle. handle.open() / handle.close() / handle.toggle() work imperatively, and handle.isOpen / handle.subscribe(cb) make it useSyncExternalStore-compatible.

import { createDrawerHandle } from '@clerk/headless/drawer';

const handle = createDrawerHandle();

<>
  <Drawer.Trigger handle={handle}>Open from anywhere</Drawer.Trigger>
  <Drawer.Root handle={handle}>{/* portal */}</Drawer.Root>
</>;

Snap points

Ascending viewport fractions the sheet can rest at (1 = full height). A slow release settles to the nearest point; a fast flick steps one point (up = larger, down = smaller, or dismiss from the first point when dismissible).

<Drawer.Root
  snapPoints={[0.4, 0.75, 1]}
  defaultActiveSnapPoint={0}
>
  {/* portal */}
</Drawer.Root>

Handle-only dragging

Only a press starting on Drawer.Handle initiates the drag; the body scrolls normally.

<Drawer.Root handleOnly>{/* portal */}</Drawer.Root>

Parts

All rendered parts accept a render prop for polymorphic rendering and standard HTML attributes for their default element. Compound parts throw if used outside Drawer.Root. Drawer.Handle is presentational (no ARIA role); keyboard users dismiss via Escape or Drawer.Close. Unlike Dialog, autoFocus defaults to false so opening on touch does not summon the virtual keyboard.

Props

Drawer.Root

Drawer.Trigger

Drawer.Viewport

Drawer.Portal accepts a root container; Drawer.Backdrop, Drawer.Popup, Drawer.Handle, Drawer.Title, Drawer.Description, and Drawer.Close take no additional props beyond standard HTML attributes for their default element.

Styling

The headless parts are unstyled. Target a part with your own class (or render prop) and combine it with the data-* state attributes each part emits:

The drag engine and snap layer write raw inputs as CSS custom properties on Drawer.Popup; the styled layer composes them into the actual transform / opacity chains (the headless layer never writes calc()). The high-frequency properties are registered as non-inheriting via registerDrawerCssVars() (a no-op where CSS.registerProperty is unavailable):

The backdrop, viewport, and popup stay mounted through the exit animation, so enter/exit transitions are CSS-driven. Sum the resting snap offset with the live drag delta so the sheet follows the finger, and drop the transition while data-swiping is present:

.drawer-popup {
  transform: translateY(calc(var(--cl-drawer-snap-point-offset, 0px) + var(--cl-drawer-swipe-movement-y, 0px)));
  transition: transform 450ms cubic-bezier(0.32, 0.72, 0, 1);
}
.drawer-popup[data-starting-style],
.drawer-popup[data-ending-style] {
  transform: translateY(100%);
}
.drawer-popup[data-swiping] {
  transition-duration: 0ms;
}
.drawer-backdrop {
  opacity: calc(0.2 * (1 - var(--cl-drawer-swipe-progress, 0)));
}