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
| Guidance | Practice |
|---|---|
| Don’t | Use the primitive in a feature. Use the styled Drawer from src/components/drawer instead. |
| Do | Call registerDrawerCssVars() once in the styled layer so the drag custom properties do not inherit. |
| Do | Set data-drawer-no-drag on any custom draggable inside the sheet. Native selects, range inputs, sliders and text selections are already excluded. |
| Do | Pass 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. |
| Do | Give Drawer.Handle a role and label if it should be announced. It is presentational; keyboard users close with Escape or Drawer.Close. |
| Don’t | Use 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.
| Prop | Type | Description |
|---|---|---|
open | boolean | Whether the drawer is open, when controlled. |
defaultOpen | boolean | Whether the drawer is open on mount, when uncontrolled.Default: false |
onOpenChange | (open: boolean) => void | Called with the new open state, including changes made through the handle. |
modal | boolean | Traps focus and blocks the rest of the page.Default: true |
handle | DrawerHandle | Connects a trigger rendered outside the root. From createDrawerHandle(). |
dismissible | boolean | Lets a drag past the threshold, an outside press or Escape close the drawer.Default: true |
handleOnly | boolean | Only a press that starts on Drawer.Handle starts a drag.Default: false |
snapPoints | number[] | Ascending viewport fractions, from 0 to 1, the sheet can rest at. |
activeSnapPoint | number | The index of the active snap point, when controlled. |
defaultActiveSnapPoint | number | The snap point index on open, when uncontrolled.Default: the last |
onActiveSnapPointChange | (index: number) => void | Called with the new snap point index. |
repositionInputs | boolean | Keeps a focused field above the virtual keyboard.Default: true |
autoFocus | boolean | Moves 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.
| Prop | Type | Description |
|---|---|---|
handle | DrawerHandle | Drives a root rendered elsewhere. Not needed inside a root. |
Drawer.Portal
Portals its children while the drawer is mounted.
| Prop | Type | Description |
|---|---|---|
root | HTMLElement | 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.
| Prop | Type | Description |
|---|---|---|
lockScroll | boolean | Locks 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.
| Prop | Type | Description |
|---|---|---|
finalFocus | FocusTarget | Where 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
<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>