useSheetSwipe

Sheet
stable

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.

typescript

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

ISheetSwipeOptions
ISheetSwipeReturn

API

Parameters

Input parameters accepted by this composable.

options
required
ISheetSwipeOptions
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

vue