JavaScript library to detect touch gestures: tap, double tap, press, long press, drag, flick, rotate, pinch, spread, pan, two-finger.
npm install the-fingerJavaScript library for detecting touch gestures on HTML elements.
Supported gesturs:
- tap
- double tap
- press
- long press
- flick / swipe
- drag
- pinch & spread
- rotate
- pan
- two finger tap
- double tap & drag
``bash`
npm install the-finger
javascript
import TheFinger from 'the-finger';const element = document.getElementById('target');
const finger = new TheFinger(element);
finger.track('tap', (gesture) => {
console.log('Tapped at:', gesture.x, gesture.y);
});
`$3
`html
`Gesture Names for
.track() Method-
tap
- double-tap
- press
- long-press
- drag (includes flick property when speed > 0.75)
- pan
- rotate
- pinch-spread
- two-finger-tap
- double-tap-and-dragAPI
$3
`javascript
new TheFinger(element, settings)
`Parameters:
-
element - HTML element to track
- settings (optional)
- preventDefault: true - Prevent default touch behavior
- visualize: true - Show touch points (requires visualizer.js)$3
#### track(gesture, callback, settings)
Start tracking a gesture.
`javascript
finger.track('drag', (gesture, touchHistory) => {
console.log(gesture.x, gesture.y);
}, {
preventDefault: 'horizontal' // 'vertical', true, or false
});
`#### untrack(gesture)
Stop tracking a gesture.
`javascript
finger.untrack('drag');
`#### on(element) / off(element)
Manually attach/detach touch listeners.
Gesture Data
Each gesture callback receives:
1.
gesture - Object with gesture-specific data (coordinates, distance, angle, etc.)
2. touchHistory - Map of touch point histories$3
- x, y - Current position
- startX, startY - Starting position
- type - Gesture type$3
- drag/pan: distance, angle, direction, speed, flick
- rotate: rotation, angleAbsolute, angleRelative
- pinch-spread: scale, distance$3
- dist/thefinger.es.js - ES module
- dist/thefinger.umd.js - UMD module
- dist/thefinger.min.js - Minified IIFE for browsersTesting
This library includes integration tests that simulate natural finger movements to verify gesture detection in a real environment using
index.html, dev/test.js, and dev/visualizer.js.$3
1. Start the development server (assumes Vite):
`bash
npm start
`2. Open the page in your browser with the
?test query parameter, e.g.: http://localhost:5173/?test
3. Check the browser console for test results, which will log PASS or FAIL for each gesture along with detection details.
Tests run sequentially for all supported gestures.
$3
Tests are implemented in
dev/test.js. To add tests for new gestures or modify existing ones:- Add the gesture name to the
gestures array in runIntegrationTests().
- Implement a new simulation function (e.g., simulateNewGesture(cx, cy, target)) that dispatches a sequence of TouchEvents to mimic the gesture's natural finger movements.
- Add a case for the new gesture in the simulateGesture() switch statement to call your new function.Simulations use programmatic
Touch objects and TouchEvent dispatching to replicate real touch interactions, including timings and position changes for realism.For example, to test a new 'swirl' gesture, you would define
simulateSwirl()` with looped touch moves in a circular pattern and add it to the test flow.ISC