# jquery-mousewheel: normalizing wheel deltas across browsers

> A jQuery plugin that turns inconsistent wheel and trackpad input into predictable deltaX and deltaY values, plus the deltaFactor that recovers the browser's own scroll distance. Here is what it does, how to wire it up, and where it stops being the right tool.

**jquery/jquery-mousewheel** — A jQuery plugin that adds cross-browser mouse wheel support.

- Repository: https://github.com/jquery/jquery-mousewheel
- Stars: 3,914 · Forks: 1,629
- Language: JavaScript
- License: NOASSERTION
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/jquery-jquery-mousewheel

## The wheel delta problem jquery-mousewheel was written to absorb

Browsers disagree about what a wheel event contains. The README states that the combination of browsers, operating systems and devices offers a huge range of possible delta values, and that a trackpad and a physical mouse wheel can differ wildly. The plugin's job is to flatten that range into a whole number starting at plus or minus 1 and increasing in increments of 1 according to force or acceleration. That number can reach into the thousands depending on the device.

The audience is narrow and specific: developers maintaining jQuery-based interfaces that already respond to wheel input, such as zoom-on-scroll canvases, custom scroll containers, or image carousels. If your code never binds to wheel input, this plugin has nothing to offer you. It does not polyfill anything else, and it does not replace jQuery.

## How the mousewheel event and deltaFactor work

You bind the mousewheel event to an element, and the plugin updates the event object with normalized deltaX and deltaY properties. The README gives this example, which also shows the helper method syntax:

```js
$( "#my_elem" ).on( "mousewheel", function( event ) {
    console.log( event.deltaX, event.deltaY, event.deltaFactor );
} );
```

The third property, deltaFactor, was added in 3.1.5. The README describes it as non-standard and explains its purpose: multiply deltaFactor by deltaX or deltaY to get the scroll distance the browser actually reported. So you get two views of the same input. The normalized delta is useful when you want consistent step sizes; the product of deltaFactor and delta is useful when you want to honour how far the browser wanted to scroll.

The README also records a deprecation. Older releases passed three arguments (delta, deltaX and deltaY) directly to the handler, and that behaviour is deprecated and will be removed in later releases. If you have handlers written against the argument style, they will need rewriting before you upgrade.

## Installing jquery-mousewheel and a first working binding

The README's build instructions are for working on the repository itself rather than consuming the package, and they start with a clone over SSH:

```sh
git clone git@github.com:jquery/jquery-mousewheel.git
cd jquery-mousewheel/
npm install
npm test
```

The npm test script runs the build, then ESLint, then the browser test suite. Note what the README says about those tests: the unit tests are very basic sanity checks, and the file explicitly invites improvements. To test the plugin properly, the README directs you to load test/index.html in each supported browser and follow the instructions at the top of the file after the unit tests finish. That is a manual step, not something the test script covers.

For consumption, package.json declares main as dist/jquery.mousewheel.js and lists dist/jquery.mousewheel.js and dist/jquery.mousewheel.min.js among the published files, so a bundler resolving the package will pick up the dist build. The peer dependency range is worth reading before you install:

```json
"peerDependencies": {
  "jquery": ">=1.12.4 <2 || >=2.2.4 <3 || >=3.6.4"
}
```

That range excludes some jQuery 2.x and 3.x releases, so a project pinned to an older 3.x line will see a peer dependency warning. Once the script is loaded, the binding in the previous section is the whole first use: attach to an element, log the three properties, and confirm that the numbers change when you use a trackpad versus a wheel.

## Where jquery-mousewheel is the wrong tool

The most concrete limitation is stated by the project itself. The README says the unit tests are very basic sanity checks, which means the automated suite is not a strong guarantee of correctness across the browser and device combinations the plugin exists to normalize. Verification is manual, and the README tells you so.

A second constraint is the dependency. This is a jQuery plugin, and package.json declares jQuery as a peer dependency rather than bundling it. If you are not already running jQuery, adding this plugin means adding jQuery too, which is a large cost for delta normalization alone.

A third issue is the version line. package.json reports version 4.0.0-pre while the most recent published releases are 3.2.0, 3.2.1 and 3.2.2, all dated 2025-03-31. The repository's default branch is ahead of the published package, so code you read in src/ may not match what you install from npm. If you need to reason about the exact behaviour you are shipping, read the dist file in the installed package rather than the source tree.

Finally, the README does not document passive event listener support. If your concern is scroll performance and you need wheel handlers that do not block the main thread, the documentation here is silent on that, and you should treat it as unverified rather than assume it works.

## jquery-mousewheel compared with mCustomScrollbar and plain wheel handling

The related search terms pair this plugin with mCustomScrollbar, and the two solve different problems. jquery-mousewheel is a normalization layer: it hands you deltaX, deltaY and deltaFactor and leaves rendering, scrollbar drawing and momentum entirely to your code. mCustomScrollbar is a scrollbar replacement, meaning it owns the visual scroll container and its own behaviour. If you want a styled scrollbar, the plugin here gives you none of that; if you want to feed normalized deltas into your own canvas or carousel, a scrollbar library would fight you for control of the same input.

The other alternative is not using a plugin at all. Modern browsers expose a native wheel event, and the plugin's value is specifically the cross-browser normalization described in the README, plus the deltaFactor property that recovers the browser's reported scroll distance. If you only target browsers whose native wheel deltas already agree in your testing, the plugin is an extra dependency for a problem you may not have.

## Licence, maintenance and upgrade cost

package.json declares the licence as MIT, while the repository metadata carries NOASSERTION, meaning the platform could not classify the licence file automatically. LICENSE.txt is present at the top level, so the authoritative text is there; read it rather than relying on either label. This is a description of what the files say, not legal advice.

On maintenance, the last push to the default branch was on 2026-09-10, and the repository is not archived. The most recent releases are 3.2.0, 3.2.1 and 3.2.2, all published on 2025-03-31. The version field in package.json reads 4.0.0-pre, so a 4.0 line is in progress on the default branch but has not appeared in the release list.

The upgrade cost is concentrated in one place. The deprecated handler arguments (delta, deltaX, deltaY) are scheduled for removal, so any code using the old signature must migrate to reading properties off the event object. The README does not document a rollback path for that change, and it does not describe a compatibility shim, so plan the migration as a code change rather than a configuration toggle. Also budget for the peer dependency range: moving to a jQuery version outside `>=1.12.4 <2 || >=2.2.4 <3 || >=3.6.4` will produce install warnings.

## Conclusion

Adopt jquery-mousewheel if you are maintaining a jQuery codebase that already binds wheel behaviour and you need one delta scale across browsers and input devices. Do not adopt it if you are starting fresh without jQuery, or if you need passive wheel listeners for scroll performance work, since the plugin predates that API and the README does not describe passive handling. Before committing, verify the peer dependency range in package.json against your jQuery version, confirm that your build pipeline produces dist/jquery.mousewheel.js from the src/ tree, and open test/index.html in each browser you support, because the README states the unit tests are only basic sanity checks.

## FAQ

### What is jquery-mousewheel used for?

It is a jQuery plugin that adds cross-browser mouse wheel support with delta normalization. Binding the mousewheel event gives you normalized deltaX and deltaY properties on the event object, plus deltaFactor for recovering the browser's reported scroll distance.

### How do I install jquery-mousewheel from npm?

package.json declares main as dist/jquery.mousewheel.js and lists the dist files among the published files, so a bundler resolving the package picks up the built file. The package also declares jQuery as a peer dependency, so your project must supply a jQuery version inside the declared range.

### What is deltaFactor in jquery-mousewheel?

It is a non-standard property added to the event object in 3.1.5. Multiply deltaFactor by deltaX or deltaY to get the scroll distance the browser reported.

### Which jQuery versions does jquery-mousewheel support?

The package.json peer dependency range is `>=1.12.4 <2 || >=2.2.4 <3 || >=3.6.4`. Versions outside that range will produce a peer dependency warning at install time.

### What is the current version of jquery-mousewheel?

The most recent published releases are 3.2.0, 3.2.1 and 3.2.2, all dated 2025-03-31. The version field in package.json reads 4.0.0-pre, so a 4.0 line exists on the default branch but has not been released.

## Sources

- [Issues](https://github.com/jquery/jquery-mousewheel/issues)
- [jquery/jquery-mousewheel on GitHub](https://github.com/jquery/jquery-mousewheel)
- [README](https://github.com/jquery/jquery-mousewheel/blob/main/README.md)
- [Releases](https://github.com/jquery/jquery-mousewheel/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/jquery-jquery-mousewheel