swipe-listener v1.3.0
Swipe-Listener
Zero-dependency, minimal swipe-gesture listener for the web.
Demo
What
Swipe-listener is a very minimal library that allows listening for swipe gesture on literally any DOM element. Once invoked with a DOM element, simply listen for swipe
event and determine the direction with the directions
object.
Example Code
var container = document.querySelector('#container');
var listener = SwipeListener(container);
container.addEventListener('swipe', function (e) {
var directions = e.detail.directions;
var x = e.detail.x;
var y = e.detail.y;
if (directions.left) {
console.log('Swiped left.');
}
if (directions.right) {
console.log('Swiped right.');
}
if (directions.top) {
console.log('Swiped top.');
}
if (directions.bottom) {
console.log('Swiped bottom.');
}
if (directions.top && directions.right) {
console.log('Swiped top-right.');
}
if (directions.top && directions.left) {
console.log('Swiped top-left.');
}
if (directions.bottom && directions.right) {
console.log('Swiped bottom-right.');
}
if (directions.bottom && directions.left) {
console.log('Swiped bottom-left.');
}
console.log('Started horizontally at', x[0], 'and ended at', x[1]);
console.log('Started vertically at', y[0], 'and ended at', y[1]);
});
Installation
Browser
<script src="path/to/swipe-listener.min.js" type="text/javascript"></script>
<script>
var container = document.querySelector('#container');
var listener = SwipeListener(container);
container.addEventListener('swipe', function (e) {
console.log(e.detail);
});
</script>
Swipe-listener is also available from unpkg: https://unpkg.com/swipe-listener@1.2.0/dist/swipe-listener.min.js
Installing using NPM
Install from NPM using npm i --save swipe-listener
, then
import SwipeListener from 'swipe-listener';
OR
const SwipeListener = require('swipe-listener');
API
SwipeListener(element, options)
element
DOM Element on which you want to enable swipe gesture tracking. This is the element on which you will be attacking theswipe
event listener.options
Optional Configuration options (see below)
Listen for swipe
event on the element
passed. Access details using event.detail
. For example, directions
can be accessed using event.detail.directions
. See events for more events.
Data passed to event.detail
:
directions
(Object)top
(Boolean) Signifies a top-swipe.right
(Boolean) Signifies a right-swipe.bottom
(Boolean) Signifies a bottom-swipe.left
(Boolean) Signifies a left-swipe.
x
(Array) Array containing two elements: starting and ending x-coords.y
(Array) Array containing two elements: starting and ending y-coords.touch
(Boolean) Whether or notTouchEvent
was used for this particular event.
Note that multiple directions can be true
at one. In case of a top-left swipe, directions.top
and directions.left
will both be true
.
Options
Key | Description | Default value |
---|---|---|
minHorizontal | Minimum number of horizontal pixels travelled for the gesture to be considered as a left or right swipe. | 10 |
minVertical | Minimum number of vertical pixels travelled for the gesture to be considered as a top or bottom swipe. | 10 |
deltaHorizontal | Maximum difference between the rightmost pixel (right-swipe) or the leftmost pixel (left-swipe) travelled to and the pixel at which the gesture is released. | 3 |
deltaVertical | Maximum difference between the bottommost pixel (bottom-swipe) or the topmost pixel (top-swipe) travelled to and the pixel at which the gesture is released. | 5 |
preventScroll | Prevents page scrolling when swiping on the DOM element. Can also be specified as a function with the signature (event) => boolean | false |
lockAxis | Enforces only one direction to be true instead of multiple. Selects the direction with the most travel. Is not enforced when the travel is equal. Example: for a top-left swipe, only one of top and left will be true instead of both. | true |
touch | Whether to listen for swipes with touch events | true |
mouse | Whether to listen for swipes with mouse events | true |
.off()
Turns off the swipe-listener on a given element.
Usage:
var listener = SwipeListener(myElem);
listener.off();
Events
swipe
- Emitted once a swipe is performed.
Emitted once a swipe is completed.
event.detail
contains
key | type | description |
---|---|---|
directions | Object | Object containing top , left , bottom , right keys. The directions in which the swipe is performed are set to true . |
x | Array | Array of two items: the starting x-coordinate and the ending x-coordinate. |
y | Array | Array of two items: the starting y-coordinate and the ending y-coordinate. |
touch | Boolean | Whether or not TouchEvent was used for this particular event. |
swiping
- Emitted while a swipe is being performed.
Emitted multiple times during a single swipe.
event.detail
contains
key | type | description |
---|---|---|
x | Array | Array of two items: the starting x-coordinate and the ending x-coordinate. |
y | Array | Array of two items: the starting y-coordinate and the ending y-coordinate. |
touch | Boolean | Whether or not TouchEvent was used for this particular event. |
swiperelease
- Emitted once the swipe is released/completed.
Emitted at the end of the swipe.
event.detail
contains
key | type | description |
---|---|---|
x | Array | Array of two items: the starting x-coordinate and the ending x-coordinate. |
y | Array | Array of two items: the starting y-coordinate and the ending y-coordinate. |
touch | Boolean | Whether or not TouchEvent was used for this particular event. |
swipecancel
- Emitted if the swipe-distance did not meet minimum travel-distance.
Emitted at the end of the swipe.
event.detail
contains
key | type | description |
---|---|---|
x | Array | Array of two items: the starting x-coordinate and the ending x-coordinate. |
y | Array | Array of two items: the starting y-coordinate and the ending y-coordinate. |
touch | Boolean | Whether or not TouchEvent was used for this particular event. |
Misc
- When
lockAxis
isfalse
, swipes using the mouse might make multiple directionstrue
even when the travel in a certain direction may not be much. You can work around this by settinglockAxis
totrue
when the page is not being accessed from a touch-enabled device. Or, you can useevent.detail.x
andevent.detail.y
to calculate which direction has more travel and consider only that direction. Or, you can increase the values ofminVertical
andminHorizontal
. TouchEvent
is not supported in IE and Edge. Unless you have polyfilled it into the page and it's available asTouchEvent
, swipes made using touch will not be detected as touch swipes.