Skip navigation

Gesture

A simple gesture API. You can use it to move the main sprite or respond to gesture events.

let { initPointer, initGesture, onGesture } = kontra;

// these functions must be called first before gesture
// functions will work
initPointer();
initGesture();

onGesture('swipeleft', function() {
  // handle swipeleft event
})

import { initPointer, initGesture, onGesture } from 'path/to/kontra.mjs';

// these functions must be called first before gesture
// functions will work
initPointer();
initGesture();

onGesture('swipeleft', function() {
  // handle swipeleft event
})

import { initPointer, initGesture, onGesture } from 'kontra';

// these functions must be called first before gesture
// functions will work
initPointer();
initGesture();

onGesture('swipeleft', function() {
  // handle swipeleft event
})

Table of Contents

Available Gestures

Below is a list of gestures that are provided by default. If you need to extend this list, you can use the gestureMap property.

  • swipeleft, swipeup, swiperight, swipedown
  • pinchin, pinchout

gestureMap

Object. A map of gesture objects to gesture names. Add to this object to expand the list of available gestures.

The gesture name should be the overall name of the gesture (e.g. swipe, pinch) and not include any directional information (e.g. left, in).

A gesture object should have a touches property and at least one touch event function. The provided gestures also have a threshold property which is the minimum distance before the gesture is recognized.

The touches property is a number that indicates how many touch points are required for the gesture. A touch event function is a function whose name should match the touch event name it triggers on (e.g. touchstart, touchmove). A touch event function is passed a touch object.

A gesture can have multiple touch event functions, but one of them must return the direction of the gesture (e.g. left, in). The gesture name and the gesture direction are combined together as the callback name for onGesture (e.g. swipeleft, pinchin).

A touch object is an array-like object where each index is a touch. A touch has the current x and y position of the touch and a start property which has the initial start x and y position.

let { gestureMap, onGesture } = kontra;

// pan is the name of the gesture
gestureMap.pan = {
  // panning uses 1 touch
  touches: 1,
  // panning is triggered on touchmove
  touchmove({ 0: touch }) {
    let x = touch.x - touch.start.x;
    let y = touch.y - touch.start.y;
    let absX = Math.abs(x);
    let absY = Math.abs(y);

    // return the direction the pan
    return absX > absY
      ? x < 0 ? 'left' : 'right'
      : y < 0 ? 'up' : 'down'
  }
};

// the gesture name and direction are combined as the callback name
onGesture('panleft', function(e, touches) {
  // handle panleft gesture
});

import { gestureMap, onGesture } from 'path/to/kontra.mjs';

// pan is the name of the gesture
gestureMap.pan = {
  // panning uses 1 touch
  touches: 1,
  // panning is triggered on touchmove
  touchmove({ 0: touch }) {
    let x = touch.x - touch.start.x;
    let y = touch.y - touch.start.y;
    let absX = Math.abs(x);
    let absY = Math.abs(y);

    // return the direction the pan
    return absX > absY
      ? x < 0 ? 'left' : 'right'
      : y < 0 ? 'up' : 'down'
  }
};

// the gesture name and direction are combined as the callback name
onGesture('panleft', function(e, touches) {
  // handle panleft gesture
});

import { gestureMap, onGesture } from 'kontra';

// pan is the name of the gesture
gestureMap.pan = {
  // panning uses 1 touch
  touches: 1,
  // panning is triggered on touchmove
  touchmove({ 0: touch }) {
    let x = touch.x - touch.start.x;
    let y = touch.y - touch.start.y;
    let absX = Math.abs(x);
    let absY = Math.abs(y);

    // return the direction the pan
    return absX > absY
      ? x < 0 ? 'left' : 'right'
      : y < 0 ? 'up' : 'down'
  }
};

// the gesture name and direction are combined as the callback name
onGesture('panleft', function(e, touches) {
  // handle panleft gesture
});

initGesture(​)

Initialize gesture event listeners. This function must be called before using other gesture functions. Gestures depend on pointer events, so initPointer must be called as well.

offGesture(​gestures)

Unregister the callback function for a gesture.

let { initPointer, initGesture, offGesture } = kontra;

initPointer();
initGesture();

offGesture('swipeleft');

import { initPointer, initGesture, offGesture } from 'path/to/kontra.mjs';

initPointer();
initGesture();

offGesture('swipeleft');

import { initPointer, initGesture, offGesture } from 'kontra';

initPointer();
initGesture();

offGesture('swipeleft');

Parameters

gestures

String or an Array of Strings. Gesture or gestures to unregister callback for.

onGesture(​gestures, callback)

Register a function to be called on a gesture event. Is passed the original Event and the touch object, an array-like object of touches.

let { initPointer, initGesture, onGesture } = kontra;

initPointer();
initGesture();

onGesture('swipeleft', function(e, touches) {
  // handle swipeleft gesture
});

import { initPointer, initGesture, onGesture } from 'path/to/kontra.mjs';

initPointer();
initGesture();

onGesture('swipeleft', function(e, touches) {
  // handle swipeleft gesture
});

import { initPointer, initGesture, onGesture } from 'kontra';

initPointer();
initGesture();

onGesture('swipeleft', function(e, touches) {
  // handle swipeleft gesture
});

Parameters

gestures

String or an Array of Strings. Gesture or gestures to register callback for.

callback

Function. Function to call on gesture events.