wheel-gestures documentation

Getting started

wheel-gestures is a small low-level open-source library that makes handling wheel events a breeze. You can use it in plain old JavaScript or with any framework.

Installation

Install wheel-gestures using your package manager:

yarn add wheel-gestures # npm install wheel-gestures

Usage

Import WheelGestures from the package into your JavaScript/TypeScript file, create an instance and add the element you want the user to start a wheel gesture on.

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) => {
  //...
})

The callback you added with .on('wheel', callback) now gets called for each recognized wheel event, with normalized information (eg. deltas) and metadata like velocity.

Avoid adding multiple elements with .observe() that are ancestors/descendants.

By default, wheel-gestures prevents the default (scrolling) on all axis. If you are only interested in allowing the user to perform a wheel gesture on one axis but keep the default behavior on the other, see the Options page and customize it.

Examples (coming soon)

  • Plain JavaScript / TypeScript
  • React
  • Vue
  • Svelte

Motivation

Due to the many differences between different browsers, operating systems and input devices, wheel events are not the easiest to work with. Which makes many developers neglect the wheel event as an input event to their web apps. Others use the wheel event already, but are overwhelmed by their complexity and handle them in a suboptimal way.

This small lib normalizes wheel events, provides useful meta data and an easier API.

License

Don't use this library to implement unresponsive page scroll jacking.

MIT.