• Stars
    star
    196
  • Rank 198,553 (Top 4 %)
  • Language
    TypeScript
  • License
    Apache License 2.0
  • Created about 6 years ago
  • Updated 12 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Very small gesture recognizer for JavaScript. Swipe, pan, tap, doubletap, longpress, pinch, and rotate.

TinyGesture.js

Very small gesture recognizer for JavaScript. Swipe, pan, tap, doubletap, and longpress.

Installation

npm install --save tinygesture

If you're upgrading from 1.0, the only breaking change in 2.0 is the location of the file. 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 swipe when diagonalSwipes is true.
  diagonalLimit: Math.tan(((45 * 1.5) / 180) * Math.PI),
  // 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.
});

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

More Repositories

1

pnotify

Beautiful JavaScript notifications with Web Notifications support.
HTML
3,650
star
2

nymph

(Deprecated) Data objects for JavaScript and PHP.
PHP
96
star
3

psteps

(Deprecated) The Pines Steps jQuery plugin.
CSS
76
star
4

pulverize

A multi-process rendering script for Blender VSE.
PHP
59
star
5

nephele

A pluggable WebDAV, CardDAV, and CalDAV server for Node.js and Express.
TypeScript
58
star
6

multicarousel

A dependency free multiple item JavaScript carousel.
HTML
35
star
7

hookphp

Method hooking in PHP.
PHP
32
star
8

ptags

(Deprecated) The Pines Tags jQuery plugin.
JavaScript
30
star
9

requirephp

An implementation of dependency injection/service location (like RequireJS) in PHP.
PHP
25
star
10

pform

The PForm CSS design.
HTML
21
star
11

2be-extras

(Deprecated) Various scripts, utilities, and documentation for 2be.
PHP
18
star
12

quickdav

Easily transfer files between your devices over your local network.
Svelte
14
star
13

pgrid

(Deprecated) The Pines Grid jQuery plugin.
CSS
13
star
14

nonblockjs

Unobtrusive (click through) UI elements in JavaScript.
JavaScript
9
star
15

pines-components

(Deprecated) Smart Industries maintained components and templates for Pines.
PHP
6
star
16

pines-core

(Deprecated) The core system of the Pines framework.
PHP
5
star
17

libsortjs

JavaScript sorting library
JavaScript
4
star
18

pines-cash-drawer

(Deprecated) A cash drawer integration utility for the Pines POS.
C
3
star
19

pines-tools

(Deprecated) Tools to assist in Pines' development.
PHP
3
star
20

itmatters

A CSS stylesheet for things that really matter.
HTML
3
star
21

svelte-strip

Strip types from Svelte files.
JavaScript
3
star
22

nymph-query-editor

(Deprecated) A Nymph query editor built with Svelte.
HTML
2
star
23

tilmeld-server

(Deprecated) Nymph user and group management with access controls.
PHP
2
star
24

nymph-examples

(Deprecated) Example apps built with Nymph.
JavaScript
2
star
25

nymph.io

The Nymph website.
HTML
2
star
26

umailphp

(Deprecated) PHP email templating system.
PHP
2
star
27

nymph-pubsub

(Deprecated) A library for publishing/subscribing to Nymph database changes.
PHP
2
star
28

nymphjs

Nymph.js - powerful data objects for Node.js and the browser.
TypeScript
2
star
29

splitn

A split function that returns [limit] elements, the last being the remainder.
TypeScript
1
star
30

nymph-directives

(Deprecated) Angular directives for Nymph.
JavaScript
1
star
31

nymph-client

(Deprecated) Client side Nymph files.
JavaScript
1
star
32

tilmeld-client

(Deprecated) Client for Tilmeld, Nymph user and group management with access controls.
JavaScript
1
star
33

nymph-client-node

(Deprecated) A wrapper for nymph-client to work in Node.js.
JavaScript
1
star
34

phpserialeditor.php

A visual editor for serialized PHP.
PHP
1
star
35

nymph-server

(Deprecated) Server side Nymph files.
PHP
1
star