Swipe

Manages swipe interactions:

• Tracks movement and detects direction
• Emits events on start, move, and end
• Supports inertia-based movement

note

• Does not transform elements, only computes coordinates.
• Does not persist state after swipe completion.

Example

Explore a live example in CodeSandbox:

Props

Static Props

Static properties are set during initialization and cannot be modified later.

Name	Description	Type	Default Value
container	Event listener container.	HTMLElement | SVGElement
buttons	Determines which mouse buttons trigger events. 0: Main button pressed, usually the left button or the un-initialized state 1: Auxiliary button pressed, usually the wheel button or the middle button (if present) 2: Secondary button pressed, usually the right button 3: Fourth button, typically the Browser Back button 4: Fifth button, typically the Browser Forward button See MouseEvent.button.	number[]	[0]
pointers	Required pointer count to activate swiping.	number	1

Mutable Props

Mutable properties can be updated at runtime using .updateProps().

Name	Description	Type	Default Value
enabled	Enables or disables swipe events.	boolean	true
relative	Calculates coordinates relative to the container.	boolean	false
axis	Primary swiping axis.	null | 'x' | 'y'	null
grabCursor	Shows "grab" and "grabbing" cursors during interaction.	boolean	false
willAbort	Determines if swipe should be aborted.	(props: ISwipeCanMoveArg) => boolean	() => false
threshold	Minimum swipe distance (px) to trigger swipe start.	number	5
minTime	Minimum duration (ms) to trigger swipe move.	number	0
directionThreshold	Minimum swipe distance (px) for directional callbacks.	number	50
preventEdgeSwipe	Prevents edge swiping (iOS swipe-back gesture).	boolean	true
edgeSwipeThreshold	Edge swipe threshold (px) from the left/right edge.	number	20
preventTouchMove	Prevents touchmove event.	boolean	true
requireCtrlKey	Requires Ctrl key for swipe (mouse only).	boolean	false
inertia	Enables inertia animation.	boolean	false
inertiaDuration	Inertia duration.	(distance: number) => number	(distance) => clamp(distance, 350, 1000)
inertiaEasing	Easing function for inertia. See easing types for more information	TEasingType	EaseOutCubic
inertiaRatio	Inertia strength.	number	0.5

Interfaces

ISwipeVec2

interface ISwipeVec2 {
  x: number;
  y: number;
}

ISwipeCanMoveArg

interface ISwipeCanMoveArg {
  type: 'touch' | 'mouse';
  matrix: ISwipeMatrix;
  start: ISwipeVec2;
  diff: ISwipeVec2;
}

ISwipeMatrix

interface ISwipeMatrix {
  x: number;
  y: number;
  angle: number;
}

ISwipeVelocity

interface ISwipeVelocity {
  x: number;
  y: number;
  angle: number;
  timestamp: number;
}

ISwipeCoords

interface ISwipeCoords {
  /** Event timestamp. */
  timestamp: number;
  /** Start position. */
  start: ISwipeMatrix;
  /** Previous position. */
  prev: ISwipeMatrix;
  /** Current position. */
  current: ISwipeMatrix;
  /** Movement offset from start. */
  diff: ISwipeMatrix;
  /** Movement offset from previous position. */
  step: ISwipeMatrix;
  /** Total accumulated movement. */
  accum: ISwipeVec2;
}

Accessors

note

All Module's accessors are available in this class.

accum

Type: ISwipeVec2

Accumulated movement.

container

Type: HTMLElement | SVGElement

Event target element.

coords

Type: ISwipeCoords

Returns current swipe coordinates.

current

Type: ISwipeMatrix

Current coordinate.

diff

Type: ISwipeMatrix

Difference between start and current coordinates.

hasInertia

Type: boolean

Indicates if inertia is active.

isSwiping

Type: boolean

Indicates if a swipe is active.

prev

Type: ISwipeMatrix

Previous coordinate.

start

Type: ISwipeMatrix

Start coordinate.

step

Type: ISwipeMatrix

Difference between start and previous coordinates.

Methods

note

All Module's methods are available in this class.

cancelInertia

Destroys the inertia animation.

instance.cancelInertia();

Callbacks

note

All Module's callbacks are available in this class.

start

Swipe start event.

// See ISwipeCoords
const destruct = instance.on('start', (coords) => console.log(coords));

// Cancel the callback
destruct();

move

Swipe move event.

// See ISwipeCoords
const destruct = instance.on('move', (coords) => console.log(coords));

// Cancel the callback
destruct();

end

Swipe end event.

// See ISwipeCoords
const destruct = instance.on('end', (coords) => console.log(coords));

// Cancel the callback
destruct();

toTop

Swipe from bottom to top.

const destruct = instance.on('toTop', () => console.log('from bottom to top'));

// Cancel the callback
destruct();

toTop

Swipe from top to bottom.

const destruct = instance.on('toBottom', () => console.log('from top to bottom'));

// Cancel the callback
destruct();

toRight

Swipe from left to right.

const destruct = instance.on('toRight', () => console.log('from left to right'));

// Cancel the callback
destruct();

toLeft

Swipe from right to left.

const destruct = instance.on('toLeft', () => console.log('from right to left'));

// Cancel the callback
destruct();

touchstart

Triggered on touchstart listener. Triggered before any action related to this event is processed.

const destruct = instance.on('touchstart', (event) => console.log(event));

// Cancel the callback
destruct();

touchmove

Triggered on touchmove listener. Triggered before any action related to this event is processed.

const destruct = instance.on('touchmove', (event) => console.log(event));

// Cancel the callback
destruct();

mousemove

Triggered on mousemove listener. Triggered before any action related to this event is processed.

const destruct = instance.on('mousemove', (event) => console.log(event));

// Cancel the callback
destruct();

abort

Triggered when swipe is aborted.

const destruct = instance.on('abort', () => console.log('swipe aborted'));

// Cancel the callback
destruct();

preventEdgeSwipe

Triggered on edge swipe preventing.

const destruct = instance.on('preventEdgeSwipe', () => console.log('edge swipe prevented'));

// Cancel the callback
destruct();

inertiaStart

Triggered on inertia start.

const destruct = instance.on('inertiaStart', () => console.log('inertia start'));

// Cancel the callback
destruct();

inertiaStart

Triggered on inertia progress.

const destruct = instance.on('inertia', () => console.log('inertia in progress'));

// Cancel the callback
destruct();

inertiaEnd

Triggered on inertia end.

const destruct = instance.on('inertiaEnd', () => console.log('inertia end'));

// Cancel the callback
destruct();