Zero-dependency, minimal swipe-gesture listener for the web.
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.
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]);
});
<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.3.1/dist/swipe-listener.min.js
Install from NPM using npm i --save swipe-listener
, then
import SwipeListener from 'swipe-listener';
OR
const SwipeListener = require('swipe-listener');
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
.
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 |
Turns off the swipe-listener on a given element.
Usage:
var listener = SwipeListener(myElem);
listener.off();
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. |
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. |
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. |
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. |
- 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.