swipe

Classify a displacement into a SwipeDirection.


Package	`@vizejs/composable/swipe`
Own the source	`vize lib pull composable:swipe`
Runtime exports	`swipeDirection`, `useSwipe`, `usePointerSwipe`
Gzip budget	4352 B

Usage

import { swipeDirection, useSwipe, usePointerSwipe } from "@vizejs/composable/swipe";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`swipeDirection`	input	experimental	safe	not-applicable	none	web, server, worker, native, desktop, terminal	—	—
`useSwipe`	input	experimental	deterministic-fallback	stable	caller, reactive-scope	web, desktop	—	`swipeDirection`, `resolveElement`, `tryOnScopeDispose`
`usePointerSwipe`	input	experimental	deterministic-fallback	stable	caller, reactive-scope	web, desktop	—	`swipeDirection`, `toPointerKind`, `resolveElement`, `tryOnScopeDispose`

API

`swipeDirection`

Classify a displacement into a SwipeDirection. Pure helper shared by the swipe composables and usable for custom gesture recognizers.

function swipeDirection( lengthX: number, lengthY: number, threshold: number, ): SwipeDirection

`useSwipe`

Detect touch swipes on an element. Tracks the first touch point from touchstart through touchend/ touchcancel. Direction is derived from the dominant axis once the travel exceeds threshold. Server renders expose zeroed coordinates and direction: "none"; listeners are removed with the owning scope.

function useSwipe(target: MaybeElementTarget, options: UseSwipeOptions = {}): SwipeControls

`usePointerSwipe`

Detect swipes from any pointer device (mouse, touch, pen). Captures the pointer on pointerdown so moves outside the element still count, and ignores secondary pointers during a gesture. Shares the state shape and SSR defaults of useSwipe.

function usePointerSwipe( target: MaybeElementTarget, options: UsePointerSwipeOptions = {}, ): SwipeControls

Types

`SwipeCallbacks`

Callbacks shared by useSwipe and usePointerSwipe.

Member	Type	Description
`onSwipeStart`?	`(event: GestureEvent) => void`	Called when a gesture starts.
`onSwipe`?	`(event: GestureEvent) => void`	Called on every move after the threshold has been exceeded.
`onSwipeEnd`?	`(event: GestureEvent, direction: SwipeDirection) => void`	Called when a gesture that exceeded the threshold ends.

`UseSwipeOptions`

Options for useSwipe.

Member	Type	Description
`onSwipeStart`?	`(event: GestureEvent) => void`	Called when a gesture starts.
`onSwipe`?	`(event: GestureEvent) => void`	Called on every move after the threshold has been exceeded.
`onSwipeEnd`?	`(event: GestureEvent, direction: SwipeDirection) => void`	Called when a gesture that exceeded the threshold ends.
`threshold`?	`number`	Minimum travel in CSS pixels before a gesture counts as a swipe.
`passive`?	`boolean`	Register passive touch listeners. Set to `false` to call `preventDefault()` on moves while swiping (for example to block pull-to-refresh).

`SwipeControls`

Reactive gesture state shared by the swipe composables.

Member	Type	Description
`isSwiping`	`Readonly<Ref<boolean>>`	Whether a gesture past the threshold is in progress.
`direction`	`ComputedRef<SwipeDirection>`	Dominant direction of the current (or last) gesture.
`coordsStart`	`Readonly<Point>`	Gesture start coordinates.
`coordsEnd`	`Readonly<Point>`	Latest gesture coordinates.
`lengthX`	`ComputedRef<number>`	`start.x - end.x`: positive when moving left.
`lengthY`	`ComputedRef<number>`	`start.y - end.y`: positive when moving up.
`stop`	`() => void`	Remove listeners. Idempotent.

`UsePointerSwipeOptions`

Options for usePointerSwipe.

Member	Type	Description
`onSwipeStart`?	`(event: GestureEvent) => void`	Called when a gesture starts.
`onSwipe`?	`(event: GestureEvent) => void`	Called on every move after the threshold has been exceeded.
`onSwipeEnd`?	`(event: GestureEvent, direction: SwipeDirection) => void`	Called when a gesture that exceeded the threshold ends.
`threshold`?	`number`	Minimum travel in CSS pixels before a gesture counts as a swipe.
`pointerTypes`?	`readonly PointerKind[]`	Device kinds that may start a gesture.
`disableTextSelect`?	`boolean`	Suppress text selection on the element while a gesture is active.