Detecting Swipes and Pinches On Touch Devices with touchSwipe Plugin

File Size: 177 KB
Views Total: 21247
Last Update:
Publish Date:
Official Website: Go to website
License: MIT
   
Detecting Swipes and Pinches On Touch Devices with touchSwipe Plugin

touchSwipe is a jQuery plugin designed for mobile touch devices that will detect when a visitor swipes or pinches a touch input device and then trigger an event/handler based on the swipe direction and distance.

Features:

  • Detects swipes in 4 directions, "up", "down", "left" and "right"
  • Detects pinches "in" and "out"
  • Supports single finger or double finger touch events
  • Supports click events both on the touchSwipe object and its child objects
  • Definable threshold / maxTimeThreshold to determine when a gesture is actually a swipe
  • Events triggered for swipe "start","move","end" and "cancel"
  • End event can be triggered either on touch release, or as soon as threshold is met
  • Allows swiping and page scrolling
  • Disables user input elements (Button, form, text etc) from triggering swipes

Installation:

# NPM
$ npm install jquery-touchswipe --save

Basic Usage:

1. Add jQuery and jQuery touchSwipe plugin in the document.

<script src="/path/to/jquery-latest.min.js"></script>
<script src="/path/to/jquery.touchSwipe.min.js"></script>
<!-- Or from a CDN -->
<script src="https://unpkg.com/jquery-touchswipe@latest/jquery.touchSwipe.min.js"></script>

2. The javascript to detect and handler the touch events.

$("#element").swipe( {
  swipe:function(event, direction, distance, duration, fingerCount, fingerData) {
    $(this).text("You swiped " + direction );  
  }
});

3. The default configuration, and available options to configure touch swipe with. You can set the default values by updating any of the properties prior to instantiation.

  • fingers: 1: The number of fingers to detect in a swipe. Any swipes that do not meet this requirement will NOT trigger swipe handlers.
  • threshold: 75: The number of pixels that the user must move their finger by before it is considered a swipe. 
  • cancelThreshold: null: The number of pixels that the user must move their finger back from the original swipe direction to cancel the gesture.
  • pinchThreshold: 20: The number of pixels that the user must pinch their finger by before it is considered a pinch. 
  • maxTimeThreshold: null: Time, in milliseconds, between touchStart and touchEnd must NOT exceed in order to be considered a swipe. 
  • fingerReleaseThreshold: 250: Time in milliseconds between releasing multiple fingers.  If 2 fingers are down, and are released one after the other, if they are within this threshold, it counts as a simultaneous release. 
  • longTapThreshold: 500: Time in milliseconds between tap and release for a long tap
  • doubleTapThreshold: 200: Time in milliseconds between 2 taps to count as a double tap
  • swipe: null: A handler to catch all swipes. See {@link $.fn.swipe#event:swipe}
  • swipeLeft: null: A handler that is triggered for "left" swipes. See {@link $.fn.swipe#event:swipeLeft}
  • swipeRight: null: A handler that is triggered for "right" swipes. See {@link $.fn.swipe#event:swipeRight}
  • swipeUp: null: A handler that is triggered for "up" swipes. See {@link $.fn.swipe#event:swipeUp}
  • swipeDown: null: A handler that is triggered for "down" swipes. See {@link $.fn.swipe#event:swipeDown}
  • swipeStatus: null: A handler triggered for every phase of the swipe. See {@link $.fn.swipe#event:swipeStatus}
  • pinchIn: null: A handler triggered for pinch in events. See {@link $.fn.swipe#event:pinchIn}
  • pinchOut: null: A handler triggered for pinch out events. See {@link $.fn.swipe#event:pinchOut}
  • pinchStatus: null: A handler triggered for every phase of a pinch. See {@link $.fn.swipe#event:pinchStatus}
  • tap: null: A handler triggered when a user just taps on the item, rather than swipes it. If they do not move, tap is triggered, if they do move, it is not. 
  • doubleTap: null: A handler triggered when a user double taps on the item. The delay between taps can be set with the doubleTapThreshold property. See {@link $.fn.swipe.defaults#doubleTapThreshold}
  • longTap: null: A handler triggered when a user long taps on the item. The delay between start and end can be set with the longTapThreshold property. See {@link $.fn.swipe.defaults#doubleTapThreshold}
  • triggerOnTouchEnd: true: If true, the swipe events are triggered when the touch end event is received (user releases finger).  If false, it will be triggered on reaching the threshold, and then cancel the touch event automatically. 
  • triggerOnTouchLeave: false: If true, then when the user leaves the swipe object, the swipe will end and trigger appropriate handlers. 
  • allowPageScroll: 'auto': How the browser handles page scrolls when the user is swiping on a touchSwipe object. See {@link $.fn.swipe.pageScroll}.
    • "auto" : all undefined swipes will cause the page to scroll in that direction.
    • "none" : the page will not scroll when user swipes.
    • "horizontal": will force page to scroll on horizontal swipes.
    • "vertical" : will force page to scroll on vertical swipes.
  • fallbackToMouseEvents: true: If true mouse events are used when run on a non touch device, false will stop swipes being triggered by mouse events on non tocuh devices. 
  • excludedElements: "button, input, select, textarea, a, .noSwipe": A jquery selector that specifies child elements that do NOT trigger swipes. By default this excludes all form, input, select, button, anchor and .noSwipe elements.
  • preventDefaultEvents: true: by default default events are cancelled, so the page doesn't move.  You can disable this so both native events fire as well as your handlers. 

Changelog:

2018-09-17

v1.6.17 (2016-05-20)

  • Fixed: fallbackToMouseEvents=false not working on IE when device supports both touch and mouse
  • check for event.cancelable in touchEnd event handler

v1.6.14 (2015-12-19)

  • Fixed double tap not working with swipes, made amd compatible

v1.6.13 (2015-12-18)

  • Built and updated docs

v1.6.12 (2015-10-02)

  • fixed handler didn't recognize more than 2 fingers

This awesome jQuery plugin is developed by mattbryson. For more Advanced Usages, please check the demo page or visit the official website.