# wheel-gestures

> wheel gestures and momentum detection

Latest version **2.3.0** (published 2026-09-07) · MIT license · 0 weekly downloads

## Install

```sh
npm install wheel-gestures
pnpm add wheel-gestures
yarn add wheel-gestures
bun add wheel-gestures
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.3.0 |
| Published | 2026-09-07 |
| First published | 2019-10-10 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18 |
| Dependencies | 0 |
| Unpacked size | 355.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 43 |
| Author | Felix Leupold |
| Maintainers | xiel |
| Keywords | wheel, scroll, mouse, trackpad, gesture, events |

## Links

- npm: https://www.npmjs.com/package/wheel-gestures
- Repository: https://github.com/xiel/wheel-gestures
- Homepage: https://github.com/xiel/wheel-gestures#readme
- Issues: https://github.com/xiel/wheel-gestures/issues
- npm.io page: https://npm.io/package/wheel-gestures

## Alternatives

- [async-exit-hook](https://npm.io/package/async-exit-hook.md) — 3.7M weekly downloads
- [evnty](https://npm.io/package/evnty.md) — 7.2K weekly downloads
- [eleventy-plugin-asciidoc](https://npm.io/package/eleventy-plugin-asciidoc.md) — 3.5K weekly downloads
- [@jswork/next-get2get](https://npm.io/package/@jswork/next-get2get.md) — 945 weekly downloads
- [@dashersw/axon](https://npm.io/package/@dashersw/axon.md) — 934 weekly downloads

## Recent versions

- 2.3.0 (latest) — 2026-09-07
- 2.2.45 (next) — 2021-06-09
- 2.2.48 — 2024-08-31
- 2.2.47 — 2024-07-04
- 2.2.46 — 2024-07-04
- 2.2.44 — 2021-06-08
- 2.2.43 — 2021-06-02
- 2.2.42 — 2021-06-02
- 2.2.41 — 2021-06-01
- 2.2.40 — 2021-06-01
- 2.2.39 — 2021-05-31
- 2.2.38 — 2021-05-31
- 2.2.37 — 2021-05-31
- 2.2.36 — 2021-05-31
- 2.2.35 — 2021-05-28
- … 51 more at https://npm.io/package/wheel-gestures/versions

## README

<h1 align="center">WheelGestures</h1>
<p align="center">
  <a href="https://wheel-gestures.xiel.dev">
    <img alt="wheel gestures animation, link to docs" src="./wheelGestures.gif" />
  </a>
</p>
<p align="center">
  wheel gestures and momentum detection in the browser
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/wheel-gestures" rel="nofollow"><img src="https://img.shields.io/npm/v/wheel-gestures/latest.svg" alt="npm (tag)" data-canonical-src="https://img.shields.io/npm/v/wheel-gestures/latest.svg" style="max-width:100%;"></a>
</p>

<hr/>

## Installation

Install wheel-gestures using your package manager:

```sh
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.

````TypeScript
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](https://wheel-gestures.xiel.dev/docs/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:

````TypeScript
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](https://wheel-gestures.xiel.dev).

When an event exposes a boolean `WheelEvent.momentum`, that value determines
`isMomentum`. Browsers without it continue to use the existing momentum detection.
Recorded events passed to `feedWheel` can also include the optional `momentum` field.

**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

---
_Source: https://npm.io/package/wheel-gestures · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._