Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


wheel gestures animation, link to docs

wheel gestures and momentum detection in the browser

npm (tag) only about 2kb minified and gzipped


Install wheel-gestures using your package manager:

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


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')

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

There are options to customize the behaviour.


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: