Drag

new

A one-axis drag gesture for mouse, pen and touch that leaves vertical scrolling to the browser on touch screens.

Demo
Drag me sideways. Let go past half my width, or flick, to dismiss.

Installation

Usage

import { useDrag } from '@/lib/drag'

const sheet = ref<HTMLElement>()

useDrag(sheet, {
  towards: 'bottom',
  onMove: (move) => (offset.value = move.movement),
  onRelease: (move) => (move.movement > 120 || move.velocity > 0.5 ? close() : (offset.value = 0)),
})

useDrag follows one axis. towards names the side whose direction counts as positive: bottom and right for down and right, top and left for up and left, so move.movement grows as the element is dragged that way and goes negative the other way. Drawer, Swipe Actions and Swipe Snap are built on it.

A press becomes a drag after 10px of travel along the axis. A mouse and a pen drag through pointer events. A finger on a touch screen drags through touch events, so the browser keeps its say over scrolling: a finger that first moves across the axis is left to scroll the page, and one that moves along it takes over. Nothing starts inside [data-no-drag] or while text is selected, and text selection is held off during a drag. When drags nest, the innermost one that starts takes the gesture; an outer drag gets it only when the inner one refuses it through canStart.

OptionDescription
towardsThe side whose direction is positive: top, bottom, left or right. A ref or a getter works too.
enabledfalse detaches the listeners.
bounds{ min, max } limits for movement; past them it rubber-bands.
canStart(move)Return false to refuse a drag once its direction is known.
onStart(move)The drag began.
onMove(move)Every move while dragging.
onRelease(move)The drag ended; move.velocity is the speed over the last 100ms, 0 after a 50ms rest.
onCancel()The drag was cancelled or the element went away.

A move carries movement (pixels along the axis), velocity (pixels per millisecond, positive towards towards), direction (1, -1 or 0), the original event, the pressed target and mouse, true for a mouse. SWIPE_VELOCITY (0.5) is the speed the drawer treats as a flick.

Changelog

  1. core 0.16.0

    97fc92b — useDrag on touch: a nested drag that refused a finger (its canStart said no) no longer starts later in the same gesture once an outer drag owns it, so a Swipe Actions row inside a Swipe Views page and the page no longer move together on a back-and-forth swipe.

    03cf21f — useDrag on touch reports each move's own velocity and direction in onMove, as the pointer path does, instead of a velocity of 0 and the direction from the start of the gesture.

  2. core 0.14.0

    6887534 — A finger drag no longer freezes when a second finger touches the screen: useDrag keeps following the first finger and releases when it lifts, so SwipeViews, useSwipeSnap, Drawer and SwipeActions settle instead of staying stuck mid-drag. A second finger that lands before the drag starts still keeps it from starting. A pen or mouse pressed during a finger drag, or a finger during a pen or mouse drag, no longer starts a second drag on top of the first.

  3. core 0.13.0

    6fb58da — Nested drags no longer start together: the innermost useDrag that starts takes the gesture, and an outer one gets it only when the inner one refuses it. A closed SwipeActions row no longer moves towards a side without actions, so that swipe reaches what is around the row. scrollBlocksDrag reads a right-to-left scroller from its start on the right.

  4. registry 0.10.0

    7e11882 — New SwipeActions item: the core swipe parts with tone-coloured actions (color, icon over label) and an opaque content layer. New drag lib item re-exporting core's useDrag, with a docs page.

  5. core 0.9.0

    7e11882 — New @kappa-ui/core/swipe-actions: SwipeRoot, SwipeItem, SwipeActions, SwipeAction, SwipeActionContent and SwipeContent, a row that slides sideways on useDrag to reveal a strip of actions on its start or end side and holds open on it, with a velocity-projected threshold, an optional full swipe that clicks the outermost action, one open row per SwipeRoot, v-model:state, outside-press, Escape and scroll dismissal, arrow keys and inert closed strips. tailwind.css adds the swipe-item utility that animates them.

  6. core 0.7.0

    92a9ce3 — @kappa-ui/core/drawer: DrawerRoot, DrawerContent, DrawerOverlay, DrawerHandle and DrawerSwipeArea over Reka UI's dialog, with a swipe-to-dismiss gesture on every side, swipe-to-open from the screen edge and a bottom edge that lifts above the virtual keyboard. New modules @kappa-ui/core/drag (useDrag over @use-gesture/vanilla with the drag-start rules) and @kappa-ui/core/virtual-keyboard (useVirtualKeyboardInset). tailwind.css gains drawer-slide and drawer-overlay-fade. @use-gesture/vanilla and @vueuse/core become dependencies. DismissReason gains "swipe".

    63adf67 — @kappa-ui/core/snap: toPixels, resolveSnapPoint and cycleSnapPoint. DrawerRoot gains snapPoints, activeSnapPoint (v-model), snapToSequentialPoints and fadeFromIndex; the content writes --drawer-snap-offset and data-expanded, the overlay --drawer-overlay-opacity, a handle tap cycles the points, and the content skips its scroll check below the largest one. useDrag reports a signed release velocity over the last 100 ms and lets a mouse drag from anywhere; releaseVerdict takes that velocity.