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

Adaptive props

To apply different values by viewport or device, use Responsive with this component as the source. Props will update automatically when breakpoints change.

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,
});