Sensors

usePointerSwipe

Reactive swipe detection based on PointerEvents. Detects swipe direction and distance.

Demo

usePointerSwipe

Detect swipe gestures using PointerEvents (mouse, touch, pen).

DistanceX

0px

DistanceY

0px

Direction: none

Idle

swipe here (mouse or touch)

Usage

Hook
Scope

import { 
const usePointerSwipe: (target: MaybeEventTarget, options?: DeepMaybeObservable<UsePointerSwipeOptions>) => UsePointerSwipeReturn
usePointerSwipe } from "@usels/web";
import { 
const useRef$: {
    <T = any>(initialValue: null): Ref$<T | null>;
    <T = any>(initialValue: T): Ref$<T>;
    <T = any>(): Ref$<T | null>;
}
useRef$ } from "@usels/core";

function 
function SwipeDemo(): JSX.Element
SwipeDemo() {
  const 
const el$: Ref$<HTMLDivElement | null>
el$ = 
useRef$<HTMLDivElement>(): Ref$<HTMLDivElement | null> (+2 overloads)
Core (framework-agnostic) version of useRef$.
Creates an observable element ref with opaque wrapping.

non-null value → Ref$<T>: current, get(), peek() return T
null / no arg → Ref$<T | null>: current, get(), peek() return T | null

Nullability is expressed via the type parameter, mirroring T | null at the call site.
useRef$<
interface HTMLDivElement
HTMLDivElement>();
  const { 
const isSwiping$: ReadonlyObservable<boolean>
Whether swiping is in progress
isSwiping$, 
const direction$: ReadonlyObservable<UseSwipeDirection>
Swipe direction
direction$, 
const distanceX$: ReadonlyObservable<number>
Distance swiped on X axis
distanceX$, 
const distanceY$: ReadonlyObservable<number>
Distance swiped on Y axis
distanceY$ } = 
function usePointerSwipe(target: MaybeEventTarget, options?: DeepMaybeObservable<UsePointerSwipeOptions>): UsePointerSwipeReturn
Framework-agnostic reactive pointer-swipe detector.
Listens to pointerdown / pointermove / pointerup on the target and
tracks swipe direction, distance, and start/end positions. options fields
are read reactively via opts$, so threshold / pointerTypes / callbacks
may be swapped at runtime.
usePointerSwipe(
const el$: Ref$<HTMLDivElement | null>
el$, {
    
threshold: number
threshold: 50,
    
onSwipeEnd: (e: any, dir: any) => any
onSwipeEnd: (
e: any
e, 
dir: any
dir) => 
any
console.
any
log(`Swiped ${
dir: any
dir}`),
  });

  return (
    <
JSX.IntrinsicElements.div: DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>
div 
RefAttributes<HTMLDivElement>.ref?: Ref<HTMLDivElement> | undefined
Allows getting a ref to the component instance.
Once the component unmounts, React will set ref.current to null
(or call the ref with null if you passed a callback ref).
@see ― https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs
ref={
const el$: Ref$<HTMLDivElement | null>
el$} 
HTMLAttributes<HTMLDivElement>.style?: CSSProperties | undefined
style={{ 
StandardLonghandProperties<string | number, string & {}>.width?: Property.Width<string | number> | undefined
This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.
Syntax: auto | <length-percentage [0,∞]> | min-content | max-content | fit-content | fit-content(<length-percentage [0,∞]>) | <calc-size()> | <anchor-size()>
Initial value: auto
| Chrome | Firefox | Safari |  Edge  |  IE   |
| :----: | :-----: | :----: | :----: | :---: |
| 1  |  1  | 1  | 12 | 4 |
@see ― https://developer.mozilla.org/docs/Web/CSS/Reference/Properties/width
width: 300, 
StandardLonghandProperties<string | number, string & {}>.height?: Property.Height<string | number> | undefined
This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.
Syntax: auto | <length-percentage [0,∞]> | min-content | max-content | fit-content | fit-content(<length-percentage [0,∞]>) | <calc-size()> | <anchor-size()>
Initial value: auto
| Chrome | Firefox | Safari |  Edge  |  IE   |
| :----: | :-----: | :----: | :----: | :---: |
| 1  |  1  | 1  | 12 | 4 |
@see ― https://developer.mozilla.org/docs/Web/CSS/Reference/Properties/height
height: 300, 
StandardShorthandProperties<string | number, string & {}>.background?: Property.Background<string | number> | undefined
This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.
Syntax: <bg-layer>#? , <final-bg-layer>
| Chrome | Firefox | Safari |  Edge  |  IE   |
| :----: | :-----: | :----: | :----: | :---: |
| 1  |  1  | 1  | 12 | 4 |
@see ― https://developer.mozilla.org/docs/Web/CSS/Reference/Properties/background
background: "#eee" }}>
      <
JSX.IntrinsicElements.p: DetailedHTMLProps<HTMLAttributes<HTMLParagraphElement>, HTMLParagraphElement>
p>Direction: {
const direction$: ReadonlyObservable<UseSwipeDirection>
Swipe direction
direction$.
ImmutableObservableBase<UseSwipeDirection>.get(trackingType?: TrackingType | GetOptions): {}
get()}</
JSX.IntrinsicElements.p: DetailedHTMLProps<HTMLAttributes<HTMLParagraphElement>, HTMLParagraphElement>
p>
      <
JSX.IntrinsicElements.p: DetailedHTMLProps<HTMLAttributes<HTMLParagraphElement>, HTMLParagraphElement>
p>
        Distance: {
const distanceX$: ReadonlyObservable<number>
Distance swiped on X axis
distanceX$.
ImmutableObservableBase<number>.get(trackingType?: TrackingType | GetOptions): {}
get()}, {
const distanceY$: ReadonlyObservable<number>
Distance swiped on Y axis
distanceY$.
ImmutableObservableBase<number>.get(trackingType?: TrackingType | GetOptions): {}
get()}
      </
JSX.IntrinsicElements.p: DetailedHTMLProps<HTMLAttributes<HTMLParagraphElement>, HTMLParagraphElement>
p>
    </
JSX.IntrinsicElements.div: DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>
div>
  );
}

import { createPointerSwipe } from "@usels/web";
import { createRef$ } from "@usels/core";

function SwipeDemo() {
  "use scope"
  const el$ = createRef$<HTMLDivElement>();
  const { direction$, distanceX$, distanceY$ } = createPointerSwipe(el$, {
    threshold: 50,
    onSwipeEnd: (e, dir) => console.log(`Swiped ${dir}`),
  });

  return (
    <div ref={el$} style={{ width: 300, height: 300, background: "#eee" }}>
      <p>Direction: {direction$.get()}</p>
      <p>
        Distance: {distanceX$.get()}, {distanceY$.get()}
      </p>
    </div>
  );
}

Reactive options

import { observable } from "@usels/core";

const threshold$ = observable(50);
const { direction$ } = usePointerSwipe(el$, { threshold: threshold$ });

// Later: adjust threshold reactively
threshold$.set(100);

Notes

options is DeepMaybeObservable. Each option field can be a plain value or an Observable. Callback options (onSwipeStart, onSwipe, onSwipeEnd) are passed as plain functions.

Type

Parameters

Parameter	Type	Description
`target`	`MaybeEventTarget`	-
`options`	`UsePointerSwipeOptions` (optional)	-

UsePointerSwipeOptions

Option	Type	Default	Description
`threshold`	`number`	`-`	Minimum distance in px to trigger swipe. Default: 50
`onSwipeStart`	`((e: PointerEvent) => void)`	`-`	Callback on swipe start
`onSwipe`	`((e: PointerEvent) => void)`	`-`	Callback on swipe move
`onSwipeEnd`	`((e: PointerEvent, direction: UseSwipeDirection) => void)`	`-`	Callback on swipe end
`pointerTypes`	`PointerType[]`	`-`	Pointer types to listen to. Default: [‘mouse’, ‘touch’, ‘pen’]
`disableTextSelect`	`boolean`	`-`	Disable text selection during swipe. Default: false

Returns

UsePointerSwipeReturn

Name	Type	Description
`isSwiping$`	`ReadonlyObservable<boolean>`	Whether swiping is in progress
`direction$`	`ReadonlyObservable<UseSwipeDirection>`	Swipe direction
`distanceX$`	`ReadonlyObservable<number>`	Distance swiped on X axis
`distanceY$`	`ReadonlyObservable<number>`	Distance swiped on Y axis
`posStart$`	`ReadonlyObservable<{ x: number; y: number; }>`	Start position
`posEnd$`	`ReadonlyObservable<{ x: number; y: number; }>`	End position
`stop`	`() => void`	Stop listening

Source

View on GitHub