wheel-gestures

What is wheel-gestures?

The wheel-gestures npm package is designed to handle wheel gestures in web applications. It provides a way to interpret and respond to wheel events, such as scrolling, with more control and precision than native browser events.

What are wheel-gestures's main functionalities?

Handling Wheel Gestures

This feature allows you to attach wheel gesture event listeners to DOM elements. The code sample demonstrates how to import the WheelGestures module, create an instance, and attach it to an element to listen for wheel gestures.

import { WheelGestures } from 'wheel-gestures';

const element = document.getElementById('myElement');
const wheelGestures = WheelGestures();

wheelGestures.on(element, (event) => {
  console.log('Wheel gesture detected:', event);
});

Customizing Gesture Sensitivity

This feature allows customization of gesture sensitivity and behavior. The code sample shows how to configure the WheelGestures instance with a custom threshold and passive option, affecting how wheel events are processed.

import { WheelGestures } from 'wheel-gestures';

const wheelGestures = WheelGestures({
  threshold: 10,
  passive: false
});

wheelGestures.on(document.body, (event) => {
  console.log('Custom sensitivity wheel gesture:', event);
});

Other packages similar to wheel-gestures

hammerjs

Hammer.js is a popular library for handling touch gestures in web applications. It supports a wide range of gestures, including pinch, rotate, and swipe, in addition to wheel gestures. Compared to wheel-gestures, Hammer.js offers broader gesture support but may be more complex to integrate for simple wheel gesture needs.

interactjs

Interact.js is a library for creating draggable, resizable, and gesturable elements. It provides comprehensive support for multi-touch gestures and interactions. While it offers more features than wheel-gestures, it might be overkill for applications that only require basic wheel gesture handling.

README

WheelGestures

wheel gestures and momentum detection in the browser

Installation

Install wheel-gestures using your package manager:

yarn add wheel-gestures # OR npm install wheel-gestures

Usage

Import and create an instance of WheelGestures and then add the element you want to observe.

import { WheelGestures } from 'wheel-gestures'

// create an instance per element
const wheelGestures = WheelGestures()

// find and observe the element the user can interact with
const element = window.document.querySelector('.slider')
wheelGestures.observe(element)

// add your event callback 
wheelGestures.on('wheel', (wheelEventState) => {
  //...
})

There are options to customize the behaviour.

WheelEventState

This is the TypeScript type of the WheelEventState object provided. Even if you do not use TypeScript, this might be helpful to see how the data is provided:

export type VectorXYZ = [number, number, number]

export interface WheelEventState {
  isStart: boolean
  isMomentum: boolean
  isEnding: boolean
  isMomentumCancel: boolean
  axisDelta: VectorXYZ
  axisVelocity: VectorXYZ
  axisMovement: VectorXYZ
  axisMovementProjection: VectorXYZ
  event: WheelEvent | WheelEventData
  previous?: WheelEventState
}

Read more in the docs.

OS & Browsers

• Mac OS (Chrome, Firefox, Safari, Edge), Magic Mouse, Magic Trackpad
• Windows (Chrome, Firefox, Edge), Microsoft Precision Touchpads

Prior Art

Other people also thought that it might be helpful for some interactions to be able to distinguish between user initiated wheel events and the ones that are triggered by inertia scroll, but none of the other known libraries delivered results in the precision I needed, so I developed my own solution. Honourable mentions:

• https://github.com/promo/wheel-indicator
• https://github.com/d4nyll/lethargy