jquery-mousewheel

What is jquery-mousewheel?

The jquery-mousewheel package is a jQuery plugin that adds cross-browser mouse wheel support. It allows you to capture mouse wheel events and respond to them in a consistent manner across different browsers.

What are jquery-mousewheel's main functionalities?

Basic Mouse Wheel Event Handling

This feature allows you to capture mouse wheel events on a specific element and log the delta value, which indicates the amount of scroll.

$(document).ready(function() {
  $("#element").on("mousewheel", function(event) {
    console.log("Mouse wheel event detected!");
    console.log("Delta: " + event.deltaY);
  });
});

Prevent Default Scrolling

This feature allows you to prevent the default scrolling behavior when a mouse wheel event is detected, which can be useful for custom scroll implementations.

$(document).ready(function() {
  $("#element").on("mousewheel", function(event) {
    event.preventDefault();
    console.log("Default scrolling prevented.");
  });
});

Custom Scroll Speed

This feature allows you to customize the scroll speed by multiplying the delta value with a custom speed factor and then adjusting the scroll position of the element.

$(document).ready(function() {
  $("#element").on("mousewheel", function(event) {
    var scrollSpeed = 10;
    var scrollAmount = event.deltaY * scrollSpeed;
    $(this).scrollTop($(this).scrollTop() - scrollAmount);
    event.preventDefault();
  });
});

Other packages similar to jquery-mousewheel

wheel

The 'wheel' package is a lightweight JavaScript library for handling mouse wheel events. It provides a simple API for capturing and responding to mouse wheel events, similar to jquery-mousewheel, but without the dependency on jQuery.

dom-helpers

The 'dom-helpers' package includes a variety of DOM utility functions, including mouse wheel event handling. It offers a more modular approach compared to jquery-mousewheel, allowing you to use only the specific utilities you need.

README

jQuery Mouse Wheel Plugin

A jQuery plugin that adds cross-browser mouse wheel support with delta normalization.

In order to use the plugin, simply bind the mousewheel event to an element.

It also provides two deprecated helper methods called mousewheel and unmousewheel that act just like other event helper methods in jQuery.

The event object is updated with the normalized deltaX and deltaY properties. In addition, there is a new property on the event object called deltaFactor. Multiply the deltaFactor by deltaX or deltaY to get the scroll distance that the browser has reported.

Here is an example of using both the bind and helper method syntax:

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

// using the event helper - not recommended!
$( "#my_elem" ).mousewheel( function( event ) {
    console.log( event.deltaX, event.deltaY, event.deltaFactor );
} );

The old behavior of adding three arguments (delta, deltaX, and deltaY) to the event handler is now deprecated and will be removed in later releases.

The Deltas...

The combination of browsers, operating systems, and devices offer a huge range of possible delta values. In fact if the user uses a trackpad and then a physical mouse wheel the delta values can differ wildly. This plugin normalizes those values so you get a whole number starting at +-1 and going up in increments of +-1 according to the force or acceleration that is used. This number has the potential to be in the thousands depending on the device.

Getting the scroll distance

In some use-cases we prefer to have the normalized delta but in others we want to know how far the browser should scroll based on the users input. This can be done by multiplying the deltaFactor by the deltaX or deltaY event property to find the scroll distance the browser reported.

The deltaFactor property was added to the event object in 3.1.5 so that the actual reported delta value can be extracted. This is a non-standard property.

Building the code in the repo & running tests

git clone [e-mail]:jquery/jquery-mousewheel.git
cd jquery-mousewheel/
npm install
npm test

The unit tests are very basic sanity checks; improvements welcome. To fully test the plugin, load test/index.html in each supported browser and follow the instructions at the top of the file after the unit tests finish.

Changelog

3.2.2

• Include the minified file in the npm package