zingtouch

A JavaScript gesture detection library for the modern web

Standard Gestures

ZingTouch provides six standard gestures that are completely customizable.
Note: These demos are best viewed on a touch capable device.

Tap

A tap event is a quick start and end of an input. Tap gestures can be configured with the amount of time inbetween a start and end, and the number of inputs it requires.

Emits

  • interval - a time measured in milliseconds between the start and end of the gesture.

Options

  • maxDelay - The maximum delay between a start and end event. This number is measured in milliseconds.
  • numInputs - The number of inputs to trigger the tap event.
  • tolerance - A tolerance value which allows the user to move their finger about a radius measured in pixels. This allows the Tap gesture to be triggered more easily since a User might move their finger slightly during a tap event.

See the Pen ZingTouch | Tap Demo by ZingChart (@zingchart) on CodePen.

See the Pen ZingTouch | Rotate by ZingChart (@zingchart) on CodePen.

Rotate

A Rotate is detected when the user has two inputs moving about a circle on the edges of a diameter.

Emits

  • angle - The angle of the initial right most input, in relation to the unit circle.
  • distanceFromOrigin - The angular distance traveled by the initial right most post.
  • distanceFromLast - The change of angle between the last position and the current position. Positive denotes a counter-clockwise motion, while negative denotes a clockwise motion.

Pinch and Expand

A pinch is detected when the user has two inputs on the screen and moves one or both closer towards the other input, while expand is detected when the two inputs move further away from each other.

Emits

  • distance - The distance in pixels between the two inputs.

Zoom in and out of the chart below by pinching and expanding two fingers on the chart itself.

See the Pen ZingTouch | Pinch&Expand by ZingChart (@zingchart) on CodePen.

Pan

A pan is detected when the user touches the screen and moves about the area.

Emits

  • distanceFromOrigin - The distance in pixels traveled from the current position from the starting position.
  • directionFromOrigin - The angle of the pan in degrees, relative to the unit circle.(e.g. straight down is 270deg while straight left is 180deg). The starting point of where the input began during the "start" event denotes the origin point.
  • currentDirection - The angle of the pan gesture in degrees, relative to the unit circle. The previously emitted point is used as an origin point.

Options

  • numInputs - The number of inputs to trigger the event.
  • threshold - The minimum number of pixels the input has to move to trigger this gesture.

Swipe

A swipe is detected when the user touches the screen and moves in a relatively increasing velocity, leaving the screen at some point before it drops below a certain velocity.

Emits

  • velocity - The value in units of pixels per millisecond the gesture was traveling until it's ending point.
  • currentDirection - The angle the swipe ended at in degrees, relative to the unit circle. (e.g. straight down is 270deg while straight left is 180deg).

Options

  • numInputs - The number of inputs to trigger the event.
  • escapeVelocity - The minimum velocity (px/ms) that the gesture has to obtain by the end event.
  • maxRestTime - The amount of time allowed in milliseconds inbetween events before the motion becomes ineligible to be a swipe

See the Pen ZingTouch | Bubble Swipe by ZingChart (@zingchart) on CodePen.

Getting Started

Adding ZingTouch to your website or application is extremely simple.

1. Include ZingTouch

ZingTouch can be included either of two different ways :

Using the import syntax (ES6)

import ZingTouch from 'zingtouch';
or

Including the script directly

<script src='./path/to/zingtouch.min.js'></script>

2. Create a Region to listen for events

Regions in ZingTouch are areas where all input events including mouse, touch, and pointer events are listened to. They hold any number of gestures you create and attach to elements.

#container
#object

Suppose we wanted to listen to some div with an id 'container' for all touch events.

var containerElement = document.getElementById('container');
var activeRegion = ZingTouch.Region(containerElement);

The region is now created and listening to every browser event inside of it.

3. Bind elements to gestures

Let's bind the Pan gesture to #object.

var childElement = document.getElementById('object');
activeRegion.bind(childElement, 'pan', function(event){
	//Perform Operations
});

Now the Pan gesture is bound to the 'object' element! Event tracking can start from the bound element, and end anywhere inside the region (including outside the bound element).

4. Try it!

Panning - Start anywhere in the child area, and move about the child or into the parent area.

See the Pen ZingTouch | Region Demo by ZingChart (@zingchart) on CodePen.

Life Cycle

ZingTouch isn't just about gestures. You can create new gestures and hook into ZingTouch's simplistic life cycle. Each gesture consists of start, move, and end events. Read More

You can make games with it!

Among the many other applications you can use ZingTouch for, one usecase is to make mobile games. We made a mini-game out of the popular Pokemon Go mobile game, using ZingTouch for the movement of the pokeball by using the Swipe and Pan gestures. If you're not already viewing this page on a mobile device open: http://codepen.io/zingchart/full/BzmdwQ/ on your mobile device for the full experience.

Documentation

Ready to Start?

Jump to our documentation on our README to learn how to use ZingTouch. ZingTouch is fully documented using JSDOC syntax and generated using ESDocs.

End-User Documentation Code Documentation

Contribute

Help support the library!

Fork us, Share us, Fix bugs with us. Any contribution is greatly appreciated.

Tweet Us Submit a Bug
Brought to you by
ZingChart is a declarative JavaScript charting library with over 25 different customizable chart types. Every visual aspect can be customized to a user's liking, and supports a rich API that integrates well into just about any app.

ZingTouch was created as a by-product for enabling ZingChart to work better on mobile devices by adding a layer of gestures for interactivity. We needed gestures to make the user experience charts more seemless between mobile-centric interactions such as zooming and panning to explore data in a chart. The ZingChart-Mobile plugin was created in order to improve these features and enable ZingChart end-users to explore data differently on a mobile device. A live example is included in the gestures section of this page.

Check us and our mobile-plugin out at www.zingchart.com