Chapter 22: Drawer

Core Idea

Drawer extends Dialog with swipe-to-dismiss gestures, snap points, and an "indent" push-back effect for the page content behind it — use it specifically when those interactions matter; a plain edge-sliding panel with no gesture need is "just a positioned Dialog" per the docs' own guidance.

Key Concepts

• Anatomy (larger than Dialog): Provider → IndentBackground, Indent → Root → Trigger, SwipeArea, Portal → Backdrop, Viewport → Popup → Content → Title, Description, Close.
• Swipe gestures: swipeDirection on Root controls which direction dismisses the drawer. Content allows text selection without swipe interference (mouse only). Add data-base-ui-swipe-ignore to any descendant that must opt out of swipe dismissal for all input types (e.g. a slider inside the drawer).
• Snap points: snapPoints, defaultSnapPoint/snapPoint/onSnapPointChange on Root; snapToSequentialPoints restricts swiping to move only to adjacent snap points rather than jumping directly to any point.
• Indent effect: Provider + Indent/IndentBackground wrap the app content to produce the "page content pushes back/scales" effect seen in native mobile bottom sheets as the drawer opens.
• Virtual keyboard awareness: wrap in Drawer.VirtualKeyboardProvider when a bottom sheet contains form fields — Base UI then manages keyboard-aware focus/scroll for the software keyboard. Drawers without this provider are unaffected by keyboard appearance.
• Nested drawers: Popup exposes data-nested-drawer-open/data-nested-drawer-swiping mirroring Dialog's nested-dialog attributes.
• Documented example set (titles only, illustrating supported patterns): State, Position, Nested drawers, Snap points, Virtual keyboard aware, Indent effect, Non-modal, Mobile navigation, Swipe to open, Close confirmation, Action sheet with a separate destructive action.

Reference Tables

Part	Notable props	Notable data attributes
Root	open/onOpenChange, swipeDirection, snapPoints, snapPoint/defaultSnapPoint, snapToSequentialPoints, modal, handle	—
Popup	initialFocus, finalFocus	data-expanded, data-swiping, data-swipe-direction, data-swipe-dismiss, data-nested-drawer-open, data-nested-drawer-swiping
SwipeArea	swipeDirection, disabled	data-swiping, data-swipe-direction
VirtualKeyboardProvider	—	wraps Root when form fields need keyboard-aware handling
Indent/IndentBackground	—	require an outer Provider

Key Takeaways

1. Use Drawer only when gestures/snap-points/indent-push are actually needed — otherwise a positioned Dialog is simpler and is the docs' own recommendation.
2. Mark any interactive element inside a drawer that shouldn't trigger swipe-dismiss (sliders, scrollable lists with horizontal swipe) with data-base-ui-swipe-ignore.
3. Always wrap in VirtualKeyboardProvider for bottom sheets containing text inputs — without it, the software keyboard can cover form fields with no automatic scroll compensation.

Connects To

• ch021 (Dialog): shared base API — Root/Backdrop/Viewport/Popup/Title/Description/Close/Handle behave the same; consult that chapter for anything not gesture/snap-specific here.
• ch004 (Releases): Drawer shipped as preview in v1.2.0, stabilized in v1.3.0 — check for behavior differences if working against an older pinned version.