Props

Static Props

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

container

• Type: HTMLElement | SVGElement
• Event listener container.

const observer = new Swipe({
  container: document.getElementById("container")
});

thumb

• Type: HTMLElement | SVGElement | null
• Default: null
• An element that triggers swipe start.
  Movement is still calculated relative to the container — thumb only defines where a user can grab.
• See demo

const observer = new Swipe({
  container: document.getElementById("container"),
  thumb: document.getElementById("thumb")
});

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.
• See demo

const observer = new Swipe({
  container: document.getElementById("container"),
  buttons: [0], // left button click
  buttons: [2], // right button click
  buttons: [0, 2], // both buttons click
});

pointers

• Type: number
• Default: 1
• Required pointer count to activate swiping.
  Useful for touch gestures such as two-finger.
  If fewer pointers are present, swipe will not start.

const observer = new Swipe({
  container: document.getElementById("container"),
  pointers: 2, // means that swipe will start only with two fingers
});

Mutable Props

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

enabled

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

const observer = new Swipe({
  container: document.getElementById("container"),
  enabled: false
});

// change value
observer.updateProps({
  enabled: true
});

relative

• Type: boolean
• Default: false
• Calculates coordinates relative to the container rather than the page.
• See demo

const observer = new Swipe({
  container: document.getElementById("container"),
  relative: true
});

// change value
observer.updateProps({
  relative: false
});

axis

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

const observer = new Swipe({
  container: document.getElementById("container"),
  axis: "x"
});

// change value
observer.updateProps({
  axis: "y"
});

ratio

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

const observer = new Swipe({
  container: document.getElementById("container"),
  ratio: 1
});

// change value
observer.updateProps({
  ratio: 2
});

grabCursor

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

const observer = new Swipe({
  container: document.getElementById("container"),
  grabCursor: true
});

// change value
observer.updateProps({
  grabCursor: false
});

willAbort

• Type: (props: ISwipeCanMoveArg) => boolean
• Default: () => false
• Runs before swipe starts and determines whether the gesture should be blocked.
  Allows disabling swipe in specific UI states or when gesture conditions are not met.

const observer = new Swipe({
  container: document.getElementById("container"),
  willAbort: () => false
});

// change value
observer.updateProps({
  willAbort: ({ diff }) => diff.x > 5, // will prevent too fast swipe
});

threshold

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

const observer = new Swipe({
  container: document.getElementById("container"),
  threshold: 5
});

// change value
observer.updateProps({
  threshold: 3
});

minTime

• Type: number
• Default: 0
• Minimum duration (ms) to trigger swipe move.
• Means that user click the container, waits some time, and only then swipe is available.

const observer = new Swipe({
  container: document.getElementById("container"),
  minTime: 0
});

// change value
observer.updateProps({
  minTime: 0
});

directionThreshold

• Type: number
• Default: 50
• Minimum swipe distance (px) for directional callbacks.
• Swipe supports direction detection (toTop, toBottom, toLeft, toRight).
• To trigger a directional callback a user must swipe a certain amount of pixels - directionThreshold.

const observer = new Swipe({
  container: document.getElementById("container"),
  directionThreshold: 50
});

// change value
observer.updateProps({
  directionThreshold: 10
});

preventEdgeSwipe

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

const observer = new Swipe({
  container: document.getElementById("container"),
  preventEdgeSwipe: true
});

// change value
observer.updateProps({
  preventEdgeSwipe: false
});

edgeSwipeThreshold

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

const observer = new Swipe({
  container: document.getElementById("container"),
  edgeSwipeThreshold: 20
});

// change value
observer.updateProps({
  edgeSwipeThreshold: 25
});

preventTouchMove

• Type: boolean
• Default: true
• Prevents touchmove from scrolling the page while swiping.
  Recommended to keep enabled for horizontal/vertical drags inside scrollable layouts.

const observer = new Swipe({
  container: document.getElementById("container"),
  preventTouchMove: true
});

// change value
observer.updateProps({
  preventTouchMove: false
});

requireCtrlKey

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

const observer = new Swipe({
  container: document.getElementById("container"),
  requireCtrlKey: true
});

// change value
observer.updateProps({
  requireCtrlKey: false
});

inertia

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

const observer = new Swipe({
  container: document.getElementById("container"),
  inertia: true
});

// change value
observer.updateProps({
  inertia: false
});

inertiaDuration

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

const observer = new Swipe({
  container: document.getElementById("container"),
  inertiaDuration: (distance) => clamp(distance, 500, 2000)
});

// change value
observer.updateProps({
  inertiaDuration: 500
});

inertiaEasing

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

const observer = new Swipe({
  container: document.getElementById("container"),
  inertiaEasing: EaseOutCubic
});

// change value
observer.updateProps({
  inertiaEasing: EaseOutBack
});

velocityModifier

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

inertiaRatio

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

const observer = new Swipe({
  container: document.getElementById("container"),
  inertiaRatio: 1
});

// change value
observer.updateProps({
  inertiaRatio: 2
});

inertiaDistanceThreshold

• Type: number
• Default: 50
• Minimum computed movement required to trigger inertia.
  If movement is smaller than this value, inertia will not play.

const observer = new Swipe({
  container: document.getElementById("container"),
  inertiaDistanceThreshold: 50
});

// change value
observer.updateProps({
  inertiaDistanceThreshold: 30
});