Hammer.js

Completely rewritten, with reusable gesture recognizers, and better support for the recent mobile browsers by making use of the touch-action css property when possible. Also support for multiple Hammer instances the same time, so multi-user became possible.

You can get the pre-build versions from the Hammer.js website, or do this by yourself running npm install -g grunt-cli && npm install && grunt build.

Getting Started

Hammer is easy to use. Just create an instance and bind the events.

var mc = Hammer(myElement);
mc.on("swipeleft swiperight", mySwipeHandler);

By default it adds the tap, doubletap and press, horizontal pan and swipe, and the multi-touch pinch and rotate recognizers. The pinch and rotate recognizers are disabled by default because they would make the element blocking, but you can enable them by calling mc.get('pinch').set({enable: true})

Also the viewport meta tag is recommended, it gives more control back to the webpage by disableing the doubletap/pinch zoom. More recent browsers that support the touch-action property don't require this.

 name="viewport" content="user-scalable=no, width=device-width, initial-scale=1, maximum-scale=1">

More control

You can setup your own set of recognizers for your instance. This requires a bit more code, but it gives you more control and slightly better performance.

var myOptions = { };
var mc = new Hammer.Manager(myElement, myOptions);

mc.add(new Hammer.Pan({ direction: Hammer.DIRECTION_ALL }));
mc.add(new Hammer.Tap({ event: 'quadrupletap', taps: 4 }));

mc.on("pan", handlePan);
mc.on("quadrupletap", handleTaps);

The example above creates an instance containing a pan and a quadrupletap gesture. The recognizer instances you create a being executed in the order they are added, and only one can be recognized at the time.

Simultaneous recognizing

If you want to recognize two gestures simultaneously, you can use the the recognizeWith() method. The example below does this with the pinch and rotate recognizers, which will improve usability.

var pinch = new Hammer.Pinch();
var rotate = new Hammer.Rotation();

pinch.recognizeWith(rotate); // recognize the pinch-rotation recognizers simultaneous

Now Hammer is able to run pinch and rotate the same time. You can also separate them with the dropRecognizeWith() method on the recognizer instance.

Require failure of an other recognizer

With the method requireFailure() you can let a recognizer require the failure of an other recognizer before recognizing. This could become useful when you want to nest two gestures, like pan-horizontal and pan-vertical.

var horizontal = new Hammer.Pan({ event: 'panh', direction: Hammer.DIRECTION_HORIZONTAL });
var vertical = new Hammer.Pan({ event: 'panv', direction: Hammer.DIRECTION_VERTICAL });

verical.requireFailure(horizontal);

Removing the dependency could be done with the dropRequireFailure() method.

The Touch-action property

Chrome 35+, IE10+ and soon FireFox, support the touch-action property. This property tells the browser how to handle touches on an element. It improves the detection and experience of the gestures a lot, because it can prevent scrolling of the page without any JavaScript has to be executed, which can be too late in some cases. Hammer uses a fallback for this property when needed, so it is working with older browsers too.

By default it sets a value based on the recognizer settings. You can overwrite this by giving the option touchAction to the Manager.

When you set the touchAction to auto it doesnt prevent any defaults, and Hammer would probably break. You have to call preventDefault manually to fix this. You should only use this if you know what you're doing.

Preferred touch-action values per gesture

If you do want to set your own value, then the table below should help you a bit...

The source code is well documented (JSDoc), you could figure out the rest of the API over there!

Hammer(HTMLElement, [options])

Creates a Manager instance with a default set of recognizers and returns the manager instance. The default set contains tap, doubletap, pan, swipe, press, pinch and rotate recognizer instances.

Hammer.Manager(HTMLElement, [options])

Create a Manager. This sets up the input event listeners, and sets the touch-action property for you on the element.

The touchAction option accepts the auto, pan-y, pan-x and none values, just like the css property. By default it is set to compute, which computes the correct touchAction property based on the added recognizers.

.add(Recognizer), .get(Recognizer) and .remove(Recognizer)

Add a new Recognizer instance to the Manager. The order of adding is also the order of the recognizers being executed. Just like the get method, it returns the added Recognizer instance.

The get and remove methods takes the event name (from a recognizer) or a recognizer instance as an argument.

.on(events, handler) and .off(events, [handler])

Listen to events triggered by the added recognizers, or remove the binded events. Accepts multiple events seperated by a space.

.stop([force])

Stop recognizing for the current input session. When forced, the recognizer cycle is stopped immediately.

.destroy()

Unbinds all events and input events and makes the manager unusable. It does NOT unbind any domEvent listeners.

Hammer.Recognizer(options)

Every Recognizer extends from this class. All recognizers also have the option enable, which is a boolean value or a callback function to enable/disable the recognizer on the fly.

.recognizeWith(otherRecognizer) and .dropRecognizeWith(otherRecognizer)

Run the recognizer simultaneous with the given other recognizer, in both directions. This is usable for like combining a pan with a swipe at the end, or a pinch with the ability to rotate the target as well. Dropping the connection only removes the link on the recognizer, not on the other recognizer.

.requireFailure(otherRecognizer) and .dropRequireFailure(otherRecognizer)

Run the recognizer only when the other recognizer fails. Dropping the connection only removes the link on the recognizer, not on the other recognizer.

Options per recognizer

Hammer.Press(options)

Recognized when the pointer is down for x ms without any movement.

Events

Hammer.Pan(options)

Recognized when the pointer is down and moved in the allowed direction.

Events

• pan
• panleft
• panright
• panup
• pandown
• panstart
• panmove
• panend
• pancancel

Hammer.Pinch(options)

Recognized when two or more pointers are moving toward (zoom-in) or away from each other (zoom-out).

Events

• pinch
• pinchin
• pinchout
• pinchstart
• pinchmove
• pinchend
• pinchcancel

Hammer.Rotate(options)

Recognized when two or more pointer are moving in a circular motion.

Events

• rotate
• rotatestart
• rotatemove
• rotateend
• rotatecancel

Hammer.Swipe(options)

Recognized when the pointer is moving fast (velocity), with enough distance in the allowed direction.

Events

• swipe
• swipeleft
• swiperight
• swipeup
• swipedown
• swipe

Hammer.Tap(options)

Recognized when the pointer is doing a small tap/click. Multiple taps are recognized if they occur between the given interval and position. The delay option can be used to recognize multi-taps without firing a single tap.

The eventData from the emitted event contains the property tapCount, which contains the amount of multi-taps being recognized.

Events

Further notes

Developed by Jorik Tangelder in his spare time and at Eight Media in Arnhem, the Netherlands.

Special thanks to Pepe Cano for his contributions.

It's recommended to listen to this loop while using hammer.js.