Swipe Snap
updatedA drag that settles on snap points measured in pixels. It is the mechanism under Swipe Views, for sheets, galleries and pagers of your own.
Up next
Installation
Usage
<script setup lang="ts">
import { ref } from 'vue'
import { useSwipeSnap } from '@/lib/swipe-snap'
const sheet = ref<HTMLElement>()
const step = ref(0)
const { snapTo } = useSwipeSnap(sheet, {
points: [0, 88, 176],
active: step,
axis: 'y',
})
</script>
<template>
<div ref="sheet" class="touch-pan-x swipe-snap translate-y-(--swipe-snap-offset)">…</div>
</template>
useSwipeSnap turns a drag into steps. points are the positions the element can rest at, in pixels along the axis, ascending from 0, and active is a ref with the index of the one it rests at. Drag the element and it follows the finger. Let go and it settles on the nearest point, or on the next one after a quick flick. A finger can catch it mid-way and drag on from where it is. Setting active from code settles there too. Swipe Views is built on it, with the points measured from its pages.
It moves nothing itself. On its element it writes --swipe-snap-offset, minus the active point at rest and live during a drag, and --swipe-snap-position, the index, fractional while moving; your classes turn them into motion. The offset grows more negative as the index grows, so translate-y-(--swipe-snap-offset) lifts the sheet above as it opens. The swipe-snap class transitions both variables, so a release settles smoothly, and turns the transition off while a finger holds the element. Give the element touch-pan-x for a vertical axis, touch-pan-y for a horizontal one, so the browser leaves the drag to it.
| Option | Description |
|---|---|
points | Snap positions along the axis in px, ascending from 0. A ref or a getter works too. |
active | A ref with the index of the active point; setting it settles there. |
axis | x or y. x by default. |
rtl | Mirrors the x axis: the variables flip, the indexes do not. |
enabled | false turns the drag off. |
sequential | One point per gesture. true by default; with false a hard flick runs to the first or the last point. |
rubberband | Let a drag stretch past the reachable points and spring back. true by default; false stops it hard. |
canStart(move) | Return false to refuse a drag that starts on the element. |
It returns the offset, position, dragging and settling refs, snapTo(index, { animate }), and attach(element, { canStart }). snapTo with { animate: false } jumps without the transition. attach makes another element start the same drag, the way Swipe Views' swipe areas do; call it during setup.
While a finger moves the element it carries data-dragging, and while it settles after a release, data-settling. A drag that starts in a scroller waits until the scroller reaches its edge, nothing starts inside [data-no-drag], and the click that ends a mouse drag is swallowed.
| Variable | Default | Description |
|---|---|---|
| --swipe-snap-offset | 0px | Minus the active point at rest, in px, and live during a drag. Mirrored with rtl. |
| --swipe-snap-position | 0 | The index of the active point, fractional while moving. |
| --swipe-snap-duration | var(--transition-duration-medium-4) | How long a release takes to settle. |