Skip to content
Mosaic
On this page

Drawer

Headless, unstyled bottom sheet with drag to dismiss, optional snap points, virtual keyboard handling and nesting. Shares the dialog behavior: portal, focus trap, scroll lock, dismissal and transitions. Ships no CSS: it writes --cl-drawer-* custom properties and data-* attributes for a styled layer to compose. createDrawerHandle() connects a root to a trigger rendered outside it.

Use for

  • the base for a styled bottom sheet
  • a sheet the user swipes down to dismiss
  • a sheet that rests at snap points, such as half and full height

Practices

GuidancePractice
Don’tUse the primitive in a feature. Use the styled Drawer from src/components/drawer instead.
DoCall registerDrawerCssVars() once in the styled layer so the drag custom properties do not inherit.
DoSet data-drawer-no-drag on any custom draggable inside the sheet. Native selects, range inputs, sliders and text selections are already excluded.
DoPass autoFocus only when the sheet should focus its first field. By default focus goes to the sheet, so a touch open does not raise the keyboard.
DoGive Drawer.Handle a role and label if it should be announced. It is presentational; keyboard users close with Escape or Drawer.Close.
Don’tUse it for a centered modal with no drag gesture. Use Dialog instead.

API reference

Drawer.Root

Holds the open, drag, snap and nesting state. Renders no element.

PropTypeDescription
openbooleanWhether the drawer is open, when controlled.
defaultOpenbooleanWhether the drawer is open on mount, when uncontrolled.Default: false
onOpenChange(open: boolean) => voidCalled with the new open state, including changes made through the handle.
modalbooleanTraps focus and blocks the rest of the page.Default: true
handleDrawerHandleConnects a trigger rendered outside the root. From createDrawerHandle().
dismissiblebooleanLets a drag past the threshold, an outside press or Escape close the drawer.Default: true
handleOnlybooleanOnly a press that starts on Drawer.Handle starts a drag.Default: false
snapPointsnumber[]Ascending viewport fractions, from 0 to 1, the sheet can rest at.
activeSnapPointnumberThe index of the active snap point, when controlled.
defaultActiveSnapPointnumberThe snap point index on open, when uncontrolled.Default: the last
onActiveSnapPointChange(index: number) => voidCalled with the new snap point index.
repositionInputsbooleanKeeps a focused field above the virtual keyboard.Default: true
autoFocusbooleanMoves focus to the first field on open instead of the sheet.Default: false

Drawer.Trigger

A button that opens the drawer. Carries data-open or data-closed.

PropTypeDescription
handleDrawerHandleDrives a root rendered elsewhere. Not needed inside a root.

Drawer.Portal

Portals its children while the drawer is mounted.

PropTypeDescription
rootHTMLElement | null | React.RefObject<HTMLElement | null>The element to portal into.Default: the `PortalProvider` container, else `document.body`

Drawer.Backdrop

A div behind the sheet. Carries data-open or data-closed and data-swiping, and gets --cl-drawer-swipe-progress to fade with the drag.

Drawer.Viewport

A fixed full-viewport div that locks scroll. Carries data-open or data-closed.

PropTypeDescription
lockScrollbooleanLocks body scroll while open.Default: true

Drawer.Popup

The sheet, a role="dialog" div that hosts the drag and the focus trap. Carries data-swiping, data-snap, data-expanded, data-nested, data-nested-drawer-open and data-nested-drawer-swiping, and the --cl-drawer-* drag, snap and nesting properties.

PropTypeDescription
finalFocusFocusTargetWhere focus goes on close: true, false, a ref, or a function of the interaction type.Default: the trigger

Drawer.Handle

The drag grip, a div with data-drawer-handle. The only drag target with handleOnly.

Drawer.Title

An h2 that names the sheet through aria-labelledby.

Drawer.Description

A p that describes the sheet through aria-describedby.

Drawer.Close

A button that closes the drawer.

Examples

A sheet with snap points

TSX
<Drawer.Root snapPoints={[0.4, 1]} defaultActiveSnapPoint={0}>
  <Drawer.Trigger>Open</Drawer.Trigger>
  <Drawer.Portal>
    <Drawer.Backdrop />
    <Drawer.Viewport>
      <Drawer.Popup>
        <Drawer.Handle />
        <Drawer.Title>Filters</Drawer.Title>
        <Drawer.Close>Done</Drawer.Close>
      </Drawer.Popup>
    </Drawer.Viewport>
  </Drawer.Portal>
</Drawer.Root>