useSheetSwipe
Encapsulates bottom-sheet swipe gesture logic using Pointer Events (covers both mouse and touch). Tracks pointerdown → pointermove → pointerup on a dedicated handle element, resolves the target snap point on release via velocity (fast flick = step one snap) or absolute distance (slow drag = nearest snap), and exposes reactive drag state for 1:1 finger tracking during the gesture.
API
Signature
Full TypeScript signature sourced from the composable file.
Only the handle element receives pointer events — the sheet body stays fully interactive (lists scroll, buttons click). The persistent prop prevents accidental dismissal; the gesture falls back to the next non-zero snap point instead of closing.
Consumed interfaces
API
Parameters
Input parameters accepted by this composable.
- optionsrequiredISheetSwipeOptions
- Configuration object. Includes el (sheet root element ref), handle (drag handle element ref), snapPoints (reactive array of TSheetSnapPoint), defaultSnap (initial snap id), disabled (Ref<boolean> to suspend gesture), and persistent (Ref<boolean> to block the closed snap).
API
Return values
Properties and methods exposed by the composable return object.
- currentSnap
- The id of the currently active snap point. Writable — programmatically call snapTo() or assign directly. Kept in sync with options.defaultSnap via a watcher.
- dragOffset
- Live pixel offset from the baseline snap height during an active drag. Positive = sheet growing (finger moving up). Resets to 0 on pointer release. Bind to a CSS translateY to achieve 1:1 finger tracking.
- isDragging
- True while a pointer is captured by the handle. Use it to suppress the sheet transition (transition: none) so the user sees immediate 1:1 tracking instead of the animated snap.
- snapTo
- Programmatically move to a named snap point. Respects the persistent constraint (cannot snap to closed when persistent=true). Resets dragOffset to 0.
- dismiss
- Convenience wrapper for snapTo("closed"). Blocked when persistent=true (falls back to the lowest non-zero snap).
- currentSnapHeight
- Resolved pixel height of the current snap point. SSR-safe (returns 0 when window is absent). Used to compute the sheet height style: currentSnapHeight + dragOffset.
Usage
Examples
Ready-to-paste usage snippets.
Basic bottom sheet with swipe gesture