tinygesture
v3.0.0
Published
Very small gesture recognizer for JavaScript. Swipe, pan, tap, doubletap, and longpress.
Downloads
12,633
Maintainers
Readme
TinyGesture.js
Very small gesture recognizer for JavaScript. Swipe, pan, tap, doubletap, longpress, pinch, and rotate.
Installation
npm install --save tinygesture
- If you're upgrading from v2, the
diagonalLimit
option has changed meaning and there are new events for pinch and rotate. Also TS now exports ES2020 instead of ES6. - If you're upgrading from v1, the location of the file has changed. It's now in a "dist" folder, hence the major version change.
Usage
Constructor and Options
import TinyGesture from 'tinygesture';
// Options object is optional. These are the defaults.
const options = {
// Used to calculate the threshold to consider a movement a swipe. it is
// passed type of 'x' or 'y'.
threshold: (type, self) =>
Math.max(
25,
Math.floor(
0.15 *
(type === 'x'
? window.innerWidth || document.body.clientWidth
: window.innerHeight || document.body.clientHeight),
),
),
// Minimum velocity the gesture must be moving when the gesture ends to be
// considered a swipe.
velocityThreshold: 10,
// Used to calculate the distance threshold to ignore the gestures velocity
// and always consider it a swipe.
disregardVelocityThreshold: (type, self) =>
Math.floor(0.5 * (type === 'x' ? self.element.clientWidth : self.element.clientHeight)),
// Point at which the pointer moved too much to consider it a tap or longpress
// gesture.
pressThreshold: 8,
// If true, swiping in a diagonal direction will fire both a horizontal and a
// vertical swipe.
// If false, whichever direction the pointer moved more will be the only swipe
// fired.
diagonalSwipes: false,
// The degree limit to consider a diagonal swipe when diagonalSwipes is true.
// It's calculated as 45deg±diagonalLimit.
diagonalLimit: 15,
// Listen to mouse events in addition to touch events. (For desktop support.)
mouseSupport: true,
};
const target = document.getElementById('target');
const gesture = new TinyGesture(target, options);
Listening to Gesture Events
gesture.on('panstart', (event) => {
// Always the original mouse or touch event.
// This service uses passive listeners, so you can't call
// event.preventDefault() on any of the events.
event;
// The (screen) x coordinate of the start of the gesture.
gesture.touchStartX;
// The (screen) y coordinate of the start of the gesture.
gesture.touchStartY;
});
gesture.on('panmove', (event) => {
// Everything from panstart, and...
// The amount the gesture has moved in the x direction.
gesture.touchMoveX;
// The amount the gesture has moved in the y direction.
gesture.touchMoveY;
// The instantaneous velocity in the x direction.
gesture.velocityX;
// The instantaneous velocity in the y direction.
gesture.velocityY;
// Boolean, whether the gesture has passed the swiping threshold in the x
// direction.
gesture.swipingHorizontal;
// Boolean, whether the gesture has passed the swiping threshold in the y
// direction.
gesture.swipingVertical;
// Which direction the gesture has moved most. Prefixed with 'pre-' if the
// gesture hasn't passed the corresponding threshold.
// One of: ['horizontal', 'vertical', 'pre-horizontal', 'pre-vertical']
gesture.swipingDirection;
// To tell if the gesture is a left swipe, you can do something like this:
if (gesture.swipingDirection === 'horizontal' && gesture.touchMoveX < 0) {
alert('You are currently swiping left.');
}
});
gesture.on('panend', (event) => {
// Everything from panstart and panmove, and...
// The (screen) x coordinate of the end of the gesture.
gesture.touchEndX;
// The (screen) y coordinate of the end of the gesture.
gesture.touchEndY;
// Swipe events are fired depending on the touch end coordinates, so
// properties like swipingDirection may be incorrect at this point, since
// they're based on the last touch move coordinates.
});
gesture.on('swiperight', (event) => {
// The gesture was a right swipe.
// This will always be true for a right swipe.
gesture.swipedHorizontal;
// This will be true if diagonalSwipes is on and the gesture was diagonal
// enough to also be a vertical swipe.
gesture.swipedVertical;
});
gesture.on('swipeleft', (event) => {
// The gesture was a left swipe.
// This will always be true for a left swipe.
gesture.swipedHorizontal;
// This will be true if diagonalSwipes is on and the gesture was diagonal
// enough to also be a vertical swipe.
gesture.swipedVertical;
});
gesture.on('swipeup', (event) => {
// The gesture was an upward swipe.
// This will be true if diagonalSwipes is on and the gesture was diagonal
// enough to also be a horizontal swipe.
gesture.swipedHorizontal;
// This will always be true for an upward swipe.
gesture.swipedVertical;
});
gesture.on('swipedown', (event) => {
// The gesture was a downward swipe.
// This will be true if diagonalSwipes is on and the gesture was diagonal
// enough to also be a horizontal swipe.
gesture.swipedHorizontal;
// This will always be true for a downward swipe.
gesture.swipedVertical;
});
gesture.on('tap', (event) => {
// The gesture was a tap. Keep in mind, it may have also been a long press.
});
gesture.on('doubletap', (event) => {
// The gesture was a double tap. The 'tap' event will also have been fired on
// the first tap.
});
gesture.on('longpress', (event) => {
// The gesture is currently ongoing, and is now a long press.
});
gesture.on('pinch', (event) => {
// The gesture is an ongoing pinch.
// This is the current scale of the pinch. <1 means the user is zooming out.
// >1 means the user is zooming in.
gesture.scale;
});
gesture.on('pinchend', (event) => {
// The pinch gesture is completed.
});
gesture.on('rotate', (event) => {
// The gesture is an ongoing rotate.
// This is the current angle of the rotation, in degrees.
gesture.rotation;
});
gesture.on('rotateend', (event) => {
// The rotate gesture is completed.
});
Long Press without Tap
If you want to listen for both long press and tap, and distinguish between them, this is how to do it.
let pressed = false;
// Note: don't use the 'tap' event to detect when the user has finished a long
// press, because it doesn't always fire.
gesture.on('tap', () => {
// If the user long pressed, don't run the tap handler. This event fires after
// the user lifts their finger.
if (pressed) {
return;
}
// ... Your tap handling code here.
});
gesture.on('longpress', () => {
// Indicate that this is a long press. This event fires before the user lifts
// their finger.
pressed = true;
// ... Your long press ongoing handling code here.
});
gesture.on('panend', () => {
// This is how you would detect when the user has finished a long press,
// because 'panend' will always fire, even if the user has moved their finger
// a little after 'longpress' has fired.
if (pressed) {
// ... Your long press finished handling code here.
// Make sure to reset pressed after the current event loop.
setTimeout(() => {
pressed = false;
}, 0);
}
});
Un-listening to Gesture Events
// There are two ways to un-listen:
const callback = (event) => {};
const listener = gesture.on('tap', callback);
// First way.
listener.cancel();
// Second way.
gesture.off('tap', callback);
Firing Events
// If, for some reason, you want to programmatically fire all the listeners for
// some event:
gesture.fire('tap', eventObj);
Destruction
// When you're done, you can remove event listeners with:
gesture.destroy();
Credits
A lot of the initial ideas and code came from:
https://gist.github.com/SleepWalker/da5636b1abcbaff48c4d
and
https://github.com/uxitten/xwiper