Tiny JavaScript Library for Touch and Mouse Swipe Detection – SwipeTracker

SwipeTracker is a lightweight JavaScript library that helps you track swipe gestures from both touch and mouse inputs.

It can be used in your web apps to detect when a user swipes on a specific DOM element and dispatch custom events that you can listen for.

How to use it:

1. Install SwipeTracker and import it into your project.

# NPM
$ npm install swipe-tracker

import SwipeTracker from 'swipe-tracker';

2. Or directly load the UMD version in your HTML document.

<script src="/dist/swipe-tracker.umd.min.js"></script>

3. Initialize SwipeTracker with options:

• container: The HTML element or a CSS selector string for the element where swipe tracking should be attached. This is the only required option.
• threshold: A number representing the minimum distance in pixels the user must swipe for the gesture to be recognized as a valid swipe. The default is 50.
• restraint: A number defining the maximum distance in pixels allowed in the direction perpendicular to the swipe. This helps prevent accidental diagonal swipes from triggering an event. The default is 100.
• buffer: The minimum movement in pixels before swipemove events begin to fire. This prevents event noise from minor pointer movements. The default is 5.
• mouse: A boolean that, when set to true, enables swipe detection from mouse input in addition to touch. The default is false.
• lock: A string that can be 'x', 'y', or 'both'. This restricts swipe detection to a specific axis, which is useful for horizontal sliders or vertical scrollers. The default is 'both'.

const el = document.querySelector('.target-element');
const tracker = new SwipeTracker({ 
  container: el 
});
tracker.init();

4. SwipeTracker dispatches custom events that you can listen for using standard addEventListener methods:

• swipe: Fired for any successful swipe gesture
• swipemove: Continuous tracking during pointer movement
• swipeleft, swiperight, swipeup, swipedown: Direction-specific swipe events

tracker.addEventListener('swipeleft', (e) => {
  eventName.textContent = 'Swipe Left';
});
tracker.addEventListener('swiperight', (e) => {
  eventName.textContent = 'Swipe Right';
});
tracker.addEventListener('swipeup', (e) => {
  eventName.textContent = 'Swipe Up';
});
tracker.addEventListener('swipedown', (e) => {
  eventName.textContent = 'Swipe Down';
});

Each event includes detailed information in the event.detail object containing coordinates, distances, direction, and pointer type.

5. You can also configure options through HTML data attributes:

<div class="target-element" 
  data-swipe
  data-swipe-threshold="60"
  data-swipe-mouse="true"
  data-swipe-lock="x">
</div>

6. API methods.

• new SwipeTracker(options): Creates a new instance.
• instance.init(): Attaches the event listeners.
• instance.destroy(): Cleans up and removes event listeners.
• SwipeTracker.getInstance(element): A static method to get the instance associated with an element.
• SwipeTracker.initAll(selector?): A handy static method to initialize all elements with data-swipe (or a custom selector).
• SwipeTracker.destroyAll(): Destroys all active instances on the page.