Skip to main content

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 on CodePen:

Props​

Static Props​

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

container​

  • Type: HTMLElement | SVGElement
  • Event listener container.

thumb​

  • Type: HTMLElement | SVGElement | null
  • Default: null
  • An element that triggers the swipe start. Calculations remain relative to the container regardless of this element.

buttons​

  • Type: number[]
  • Default: [0]
  • 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.

pointers​

  • Type: number
  • Default: 1
  • Required pointer count to activate swiping.

Mutable Props​

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

enabled​

  • Type: boolean
  • Default: true
  • Enables or disables swipe events.

relative​

  • Type: boolean
  • Default: false
  • Calculates coordinates relative to the container.

axis​

  • Type: null | 'x' | 'y'
  • Default: null
  • Primary swiping axis.

ratio​

  • Type: number
  • Default: 1
  • Swipe move ratio (multiplier).

grabCursor​

  • Type: boolean
  • Default: false
  • Shows "grab" and "grabbing" cursors during interaction.

willAbort​

  • Type: (props: ISwipeCanMoveArg) => boolean
  • Default: () => false
  • Determines if swipe should be aborted.

threshold​

  • Type: number
  • Default: 5
  • Minimum swipe distance (px) to trigger swipe start.

minTime​

  • Type: number
  • Default: 0
  • Minimum duration (ms) to trigger swipe move.

directionThreshold​

  • Type: number
  • Default: 50
  • Minimum swipe distance (px) for directional callbacks.

preventEdgeSwipe​

  • Type: boolean
  • Default: true
  • Prevents edge swiping (iOS swipe-back gesture).

edgeSwipeThreshold​

  • Type: number
  • Default: 20
  • Edge swipe threshold (px) from the left/right edge.

preventTouchMove​

  • Type: boolean
  • Default: true
  • Prevents touchmove event.

requireCtrlKey​

  • Type: boolean
  • Default: false
  • Requires Ctrl key for swipe (mouse only).

inertia​

  • Type: boolean
  • Default: false
  • Enables inertia animation.

inertiaDuration​

  • Type: (distance: number) => number
  • Default: (distance) => clamp(distance, 500, 2000)
  • Inertia duration.

inertiaEasing​

  • Type: TEasingType
  • Default: EaseOutCubic
  • Easing function for inertia.
  • See easing types for more information.

velocityModifier​

  • Type: false | ((velocity: ISwipeMatrix) => ISwipeMatrix)
  • Default: false
  • Final velocity modifier. Accepts and returns additional movement.

inertiaRatio​

  • Type: number
  • Default: 1
  • Inertia strength.

inertiaDistanceThreshold​

  • Type: number
  • Default: 50
  • Minimum calculated distance to trigger inertia.

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();

toBottom​

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();

inertiaFail​

Triggered when inertia fails to start because of lack of momentum.

const destruct = instance.on('inertiaFail', () => console.log('inertia fail'));

// Cancel the callback
destruct();

inertiaCancel​

Triggered when inertia is cancelled.

const destruct = instance.on('inertiaCancel', () => console.log('inertia cancel'));

// Cancel the callback
destruct();