search

GianlucaGuarini / Tocca.js

Super lightweight script (~1kb) to detect via Javascript events like 'tap' 'dbltap' 'swipeup' 'swipedown' 'swipeleft' 'swiperight' on any kind of device.
http://gianlucaguarini.github.io/Tocca.js/
MIT License
660 stars 60 forks source link

readme

Tocca.js

Build Status

NPM version NPM downloads

MIT License

CDNJS

Super lightweight script ( ~1kB ) to detect via Javascript events like 'tap' 'longtap' 'dbltap' 'swipeup' 'swipedown' 'swipeleft' 'swiperight' on any kind of device.

Demo

Donations

If this project helped getting your job done consider making a donation for all the time I spend to bring it to you

Donate

Installation

Npm

$ npm install tocca

Bower

$ bower install Tocca.js -save

Usage

Include the script into your page:

<script src="https://github.com/GianlucaGuarini/Tocca.js/raw/master/path/to/Tocca.js"></script>

Once you have included Tocca.js you will be able to catch all the new events:

elm.addEventListener('tap',function(e){});
elm.addEventListener('dbltap',function(e){});
elm.addEventListener('longtap',function(e){});
elm.addEventListener('swipeleft',function(e){});
elm.addEventListener('swiperight',function(e){});
elm.addEventListener('swipeup',function(e){});
elm.addEventListener('swipedown',function(e){});

It works with jQuery as well:

$(elm).on('tap',function(e,data){});
$(elm).on('dbltap',function(e,data){});
$(elm).on('longtap',function(e,data){});
$(elm).on('swipeleft',function(e,data){});
$(elm).on('swiperight',function(e,data){});
$(elm).on('swipeup',function(e,data){});
$(elm).on('swipedown',function(e,data){});

Tocca.js supports also the inline events if you are using Riot.js!

<div ontap="function(e){})"></div>
<div ondbltap="function(e){})"></div>
<div onlongtap="function(e){})"></div>
<div onswipeleft="function(e){})"></div>
<div onswiperight="function(e){})"></div>
<div onswipeup="function(e){})"></div>
<div onswipedown="function(e){})"></div>

API and Examples

Anytime you will use a Tocca.js event the callback function will receive a special event object containing the following properties

Examples:

elm.addEventListener('dbltap',function (e){
  console.log(e.x);
  console.log(e.y);
});
elm.addEventListener('swipeup',function (e){
  console.log(e.x);
  console.log(e.y);
  console.log(e.distance.x);
  console.log(e.distance.y);
});

// with jQuery

$(elm).on('dbltap',function (e,data){
  console.log(data.x);
  console.log(data.y);
});
$(elm).on('swipeup',function (e,data){
  console.log(data.x);
  console.log(data.y);
  console.log(data.distance.x);
  console.log(data.distance.y);
});

Anyway you can combine Tocca.js with the default javascript touch events:

To disable the default touch behaviours (zoom on double tap, scroll on swipe...) on a certain element via javascript you can always use the following snippet:

elm.addEventListener('touchmove',function(e){e.preventDefault()});
elm.addEventListener('touchstart',function(e){e.preventDefault()});
elm.addEventListener('touchend',function(e){e.preventDefault()});

Configuration

Whenever you want to configure the plugin events settings you can do that simply specifying two constants before including Tocca.js into the page

<script>
var SWIPE_THRESHOLD = 100, // default value
  DBL_TAP_THRESHOLD = 200, // range of time in which a dbltap event could be detected,
  LONG_TAP_THRESHOLD = 1000, // range of time after which a longtap event could be detected
  TAP_THRESHOLD = 150, // range of time in which a tap event could be detected
  TAP_PRECISION = 60 / 2, // default value (touch events boundaries)
  JUST_ON_TOUCH_DEVICES = false, // default value ( decide whether you want to use the Tocca.js events only on the touch devices )
  IGNORE_JQUERY = false; // default value ( will not use jQuery events, even if jQuery is detected )
</script>
<script src="https://github.com/GianlucaGuarini/Tocca.js/raw/master/path/to/Tocca.js"></script>

In Tocca.js 1.1.0 you can also configure/get the internal options via function:

window.tocca({
  useJquery: your new option
  swipeThreshold: your new option
  tapThreshold: your new option
  dbltapThreshold: your new option
  longtapThreshold: your new option
  tapPrecision: your new option
  justTouchEvents: your new option
})

console.log(window.tocca()) // will always return the current internal options

Browser Support

Actually the script has been tested on all the modern browsers but it need a better testing phase over several platforms: Chrome 29+ Firefox 23+ Opera 12+ Safari 5+

It works on mobile/tablet browsers and on desktop browsers as well.

On the old browsers all the Tocca.js events cannot be triggered.

Changelog

2.0.9

2.0.8

2.0.7

2.0.6

2.0.5

2.0.4

2.0.3

2.0.1

2.0.0

1.1.0

1.0.1

1.0.0

Thanks to @AndyOGo for his help on this release

0.2.0

0.1.7

0.1.5

0.1.4

0.1.3

0.1.2

0.1.1

0.1.0

0.0.8

0.0.7

0.0.6

0.0.5

0.0.4

0.0.3

0.0.2

What does Tocca mean?!

'Tocca' is the second person singular of the imperative Italian verb 'Toccare' that means to touch.