Drawer
Present a swipeable surface from a viewport edge with snap points.
Anatomy#
Content is portaled. Overlay and Content are siblings by default.
Usage#
Use Drawer for a mobile-style surface the user dismisses with a swipe along its edge, optionally resting at snap points. Use Sheet for an edge panel without gestures. Use Dialog for a centered labeled task, and BaseDialog to compose backdrop and content yourself.
Drawer shares modal dismissal and focus behavior with Dialog. The default side is bottom. For a
persistent panel that coexists with the page, combine modal={false} with overlay={false},
preventScroll={false}, and closeOnOverlayClick={false}. Escape and swipe dismissal still apply.
Content composition#
Use Content title and description for simple cases, or compose Drawer.Header, Drawer.Title,
Drawer.Description, Drawer.Body, and Drawer.Footer for a custom layout, following the same
contract as Sheet. An explicit Drawer.Header replaces the
generated header. Drawer.Close is an explicit close control. Root closable (default true) adds
the automatic corner close button, and closeIcon replaces its icon. The drawer message group
(close) names the button, and translations overrides it per drawer. A touch swipe that starts
on the button still dismisses.
Root transition={false} turns off the enter and exit animations. Content and overlay then unmount
as soon as the drawer closes instead of waiting for the animation to end.
For top and bottom sides, Content renders a decorative handle grab bar along the edge facing
the viewport. Set handle={false} to hide it.
Sizing and scrolling#
A top or bottom drawer sizes to its content and stops 0.5rem (or the top safe-area inset, if
larger) short of the viewport height. left and right panels span w-3/4, up to sm:max-w-sm.
Override either with Content class, for example class="h-[50dvh]" for a fixed height or
class="w-1/2 sm:max-w-2xl" for a wider side panel. Body is the scrollable region: once Content’s
height is bounded, it scrolls between the header and footer.
Swipe to dismiss#
The surface tracks a drag along its dismiss axis (down for bottom, up for top, outward for
left and right) and closes once dragged past half its size or on a fast flick. A drag against
the dismiss direction is damped and springs back. The data-swiping attribute on the content and
overlay marks the active gesture so transitions pause.
A mouse or pen drag does not start on interactive elements (button, a, form controls,
[contenteditable], [role="button"], [role="slider"]), inside Drawer.Body, which stays
available for text selection, or inside a region that scrolls along the drag axis. A touch drag can start on interactive
elements. Touch drags that begin inside a scrollable region defer to native scrolling until the
scroller reaches its edge in the drag direction.
Mark a subtree with data-swipe-ignore to block drags that start in it. On touch,
data-swipe-ignore="x" or "y" blocks only drags along that axis.
Snap points#
snapPoints limits where a top or bottom drawer rests. Each entry is the visible height from the
edge, in any order: numbers <= 1 are a fraction of the viewport height, larger numbers are pixels,
and 'px' or 'rem' strings resolve directly. Snap points are ignored for left and right. Snap
heights are clamped to the content’s rendered height and the viewport, so give Content an explicit
height (for example class="h-[calc(100dvh-0.5rem)]") when using fractional or full snap points.
snapPoint, defaultSnapPoint, and onSnapPointChange control the resting point. It defaults to
the first snap point, and null means fully open. Releasing a swipe settles on the closest point
(projected by the swipe velocity), and dragging past the lowest point closes the drawer. With
snapToSequentialPoints, a flick advances at most one point and closes only from the lowest point.
After the drawer finishes closing, it returns to the default point and reports it through
onSnapPointChange if the active point differed.
CSS variables#
Content declares these variables. Override them with styles.content, or read them in your own styles.
| Variable | Default | Description |
|---|---|---|
--drawer-swipe-movement |
0px |
Current swipe offset along the surface axis. |
--drawer-snap-point-offset |
0px |
Offset of the active snap point from fully open. |
--drawer-keyboard-inset |
0px |
Bottom inset reserved for the on-screen keyboard. |
--drawer-translate |
per side | Translate applied to the surface; derives from the swipe and snap offsets. |
--drawer-max-height |
calc(100dvh - max(0.5rem, env(safe-area-inset-top, 0px))) |
Height cap for top and bottom sides. |
--drawer-safe-area-bottom |
env(safe-area-inset-bottom, 0px) |
Resolved bottom safe-area inset. |
--drawer-bottom-inset |
max of safe area and --drawer-keyboard-inset |
Bottom padding of a bottom drawer. |
--drawer-nested-num |
0 |
Number of open drawers nested inside this drawer. |
--drawer-nested-progress |
0 |
Swipe progress of the frontmost nested drawer in [0, 1]. |
--drawer-frontmost-height |
0px |
Measured popup height of the frontmost nested drawer. |
--drawer-nested-scale |
derived from nested count and progress (1 when none) |
Scale applied to recede ancestor drawers in a nested stack. |
--drawer-nested-offset |
derived from nested count and progress (0px when none) |
Offset applied to push ancestor drawers upward in a nested stack. |
Keyboard interaction#
| Key | Description |
|---|---|
| Esc | Dismisses the drawer unless closeOnEscape is false. |
| ⇥ | Moves focus forward; modal drawers contain focus. |
| Shift + Tab | Moves focus backward; modal drawers contain focus. |
On Android, the system back gesture closes the drawer in browsers that support CloseWatcher. It
follows closeOnEscape and reports blocked requests through onClosePrevented.
Examples#
Bottom sheet with a handle#
The default bottom side shows the grab handle and dismisses on a downward swipe.
Rest at snap points#
A controlled snap point switches between a compact peek and the full-height surface.
Nest drawers#
A child drawer opens above its parent: ancestors shrink and slide up behind it. Setting
overlay={false} on the nested drawers keeps a single overlay for the whole stack.
Escape, swipe, outside press, and the Android back gesture close only the topmost drawer.
Open from different edges#
Top and bottom support handles and snap points; left and right are swipe-only panels.
Keep the page interactive#
modal={false}, overlay={false}, and preventScroll={false} leave the page’s pointer, focus,
and scroll access intact; closeOnOverlayClick={false} keeps outside presses from dismissing the
panel — both buttons update the same count.
Swap Dialog and Drawer responsively#
createMediaQuery renders the same task in a Dialog on wide screens and a
Drawer on narrow ones. Resize the window to see the trigger swap.
API Reference#
Attributes#
data-closeddata-disableddata-expandeddata-swipingdata-transitiondata-handledata-nested-opendata-nested-swipingdata-footerdata-headerdata-bodyProps#
Drawer#
Trigger#
Renders a <button> element by default.
Content#
Props for Drawer.Content. Renders a <div> element by default.
Header#
Renders a <div> element by default.
Title#
Renders a <h2> element by default.
Description#
Renders a <p> element by default.
Body#
Renders a <div> element by default.
Footer#
Renders a <div> element by default.
Close#
Renders a <button> element by default.