Swipe Snap

updated

A drag that settles on snap points measured in pixels. It is the mechanism under Swipe Views, for sheets, galleries and pagers of your own.

Demo

Up next

Blue in Green

Miles Davis

Naima

John Coltrane

Peace Piece

Bill Evans

Moanin'

Art Blakey

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.

OptionDescription
pointsSnap positions along the axis in px, ascending from 0. A ref or a getter works too.
activeA ref with the index of the active point; setting it settles there.
axisx or y. x by default.
rtlMirrors the x axis: the variables flip, the indexes do not.
enabledfalse turns the drag off.
sequentialOne point per gesture. true by default; with false a hard flick runs to the first or the last point.
rubberbandLet 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.

VariableDefaultDescription
--swipe-snap-offset0pxMinus the active point at rest, in px, and live during a drag. Mirrored with rtl.
--swipe-snap-position0The index of the active point, fractional while moving.
--swipe-snap-durationvar(--transition-duration-medium-4)How long a release takes to settle.

Changelog

  1. registry 0.24.1

    35a5371 — No component styles an element through a :has() on its parent or group any more. Chrome restyles the whole subtree of every :has() anchor above a node that is added or removed, once some rule puts :has() away from the element it styles: a page wrapped in one such anchor recalculated every element for each list row it mounted. The Dialog, Drawer and Tour headers, the InputGroup and InputNumber insets, the Combobox clear button, the InputFloating notch, a FieldLabel beside a disabled checkbox or radio, the Rating ring, and the Slider and ScrollArea examples now read their neighbours with ~ or a :has() on the element itself. The InputGroup addons fade through a variable that the group sets. FileUpload, Image, Marquee and DataTable mark the state on an element instead: the hidden input's focus, an ImageError inside, keyboard focus, and the body above pinned bottom rows. scripts/has-selectors.test.ts keeps the pattern out.

    useSwipeSnap no longer flushes styles for an instant move that leaves the offset where it is, such as new points at rest.

  2. core 0.17.1

    35a5371 — No component styles an element through a :has() on its parent or group any more. Chrome restyles the whole subtree of every :has() anchor above a node that is added or removed, once some rule puts :has() away from the element it styles: a page wrapped in one such anchor recalculated every element for each list row it mounted. The Dialog, Drawer and Tour headers, the InputGroup and InputNumber insets, the Combobox clear button, the InputFloating notch, a FieldLabel beside a disabled checkbox or radio, the Rating ring, and the Slider and ScrollArea examples now read their neighbours with ~ or a :has() on the element itself. The InputGroup addons fade through a variable that the group sets. FileUpload, Image, Marquee and DataTable mark the state on an element instead: the hidden input's focus, an ImageError inside, keyboard focus, and the body above pinned bottom rows. scripts/has-selectors.test.ts keeps the pattern out.

    useSwipeSnap no longer flushes styles for an instant move that leaves the offset where it is, such as new points at rest.

  3. core 0.16.0

    1ebc3d6 — useSwipeSnap clamps an active index outside its points when it starts, so active 5 over three points rests on the last one instead of writing an offset of 0 and a position of 5.

  4. 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.

  5. registry 0.17.0

    6c50288 — New SwipeViews: pages that follow the finger, the way native apps page between tabs. It holds the page in the frame in v-model, pairs with Tabs on the same model, and lays its SwipeViews out in a row that a swipe or a flick moves along. layout="stack" lays the pages on top of each other, each sliding in over the one before it, as in a navigation stack. The frame and every page carry CSS variables for layouts and effects of your own. SwipeViewsSwipeArea adds a strip at an edge, and swipe-area-only makes it the only way to swipe. The mechanism underneath comes as its own item, swipe-snap, with useSwipeSnap for sheets, galleries and pagers of your own.

  6. core 0.13.0

    7200c46 — New @kappa-ui/core/swipe-snap: useSwipeSnap pages between snap points measured in px. A drag follows the finger, the release settles on the nearest point or the next one after a flick, and a finger can catch a settle mid-way. rubberband: false stops a drag hard at the edge instead of letting it stretch. It writes --swipe-snap-offset and --swipe-snap-position on its element for CSS to move things with; the new swipe-snap utility transitions them and swipe-view passes them one level down.