jQuery Mousewheel Plugin: Wheel Events, Deltas & Examples

jQuery Mousewheel is a jQuery plugin that normalizes mouse wheel input into a consistent mousewheel event.

It adds normalized deltaX and deltaY values plus deltaFactor for jQuery projects that need vertical or horizontal wheel data across browsers and input devices.

Features:

• Normalized vertical and horizontal wheel deltas.
• Whole-number deltaX and deltaY values across different delta scales.
• deltaFactor for recovering the wheel distance reported by the browser.
• Conversion of line-based and page-based wheel data before delta normalization.
• Optional normalization of offsetX and offsetY.

How to Use jQuery Mousewheel

1. Load jQuery and the plugin

Load jQuery before jquery.mousewheel.min.js.

<script src="jquery.min.js"></script>
<script src="jquery.mousewheel.min.js"></script>

The npm package is also available for projects that manage frontend dependencies through a package manager:

npm install jquery-mousewheel

2. Add a target element

<div id="wheel-demo">Scroll over this area</div>
<p id="wheel-output"></p>

3. Bind the mousewheel event

$("#wheel-demo").on("mousewheel", function(event) {
  $("#wheel-output").text(
    "deltaX: " + event.deltaX +
    ", deltaY: " + event.deltaY +
    ", deltaFactor: " + event.deltaFactor
  );
});

How Wheel Delta Normalization Works

Browsers, operating systems, mouse wheels, and trackpads can report wheel deltas at very different scales. jQuery Mousewheel converts those values to whole normalized steps that start at +1 or -1 and increase with stronger wheel input.

The plugin also converts line-based and page-based native wheel data to pixel-based values before normalization. After processing, event.deltaMode is set to 0.

deltaY Direction: Positive and Negative Values

The plugin preserves the legacy mousewheel sign convention. A positive event.deltaY represents upward wheel input, and a negative value represents downward wheel input.

$("#wheel-demo").on("mousewheel", function(event) {
  if (event.deltaY > 0) {
    $("#wheel-output").text("Wheel up");
  } else if (event.deltaY < 0) {
    $("#wheel-output").text("Wheel down");
  }
});

The native wheel event uses the opposite vertical sign when jQuery Mousewheel processes its deltaY value. Do not copy the same direction test between the two event APIs without adjusting the sign.

Event Properties

• event.deltaX: Normalized horizontal wheel delta.
• event.deltaY: Normalized vertical wheel delta.
• event.deltaFactor: Factor used to recover the wheel distance reported by the browser from a normalized delta.
• event.deltaMode: Set to 0 after line-based or page-based values are converted.
• event.offsetX: Horizontal pointer offset relative to the bound element when offset normalization is active.
• event.offsetY: Vertical pointer offset relative to the bound element when offset normalization is active.

Get the Reported Wheel Distance

Multiply deltaFactor by a normalized delta when the interface needs the wheel distance reported by the browser.

$("#wheel-demo").on("mousewheel", function(event) {
  var distanceX = event.deltaFactor * event.deltaX;
  var distanceY = event.deltaFactor * event.deltaY;

  console.log("X distance:", distanceX);
  console.log("Y distance:", distanceY);
});

Plugin Settings

• $.event.special.mousewheel.settings.adjustOldDeltas: Boolean. Default: true. Adjusts older mousewheel deltas that use values divisible by 120.
• $.event.special.mousewheel.settings.normalizeOffset: Boolean. Default: true. Calculates normalized offsetX and offsetY values for wheel events.
• $.event.special.mousewheel.version: Exposes the loaded plugin version string.

Disable Old Delta Adjustment

$.event.special.mousewheel.settings.adjustOldDeltas = false;

Disable Offset Normalization

$.event.special.mousewheel.settings.normalizeOffset = false;

Binding and Unbinding Events

Keep a reference to the handler when the listener needs to be removed later.

function handleWheel(event) {
  console.log(event.deltaX, event.deltaY, event.deltaFactor);
}

$("#wheel-demo").on("mousewheel", handleWheel);

// Remove the same handler.
$("#wheel-demo").off("mousewheel", handleWheel);

Deprecated Helper Methods

• .mousewheel(handler): Binds a mousewheel handler. Deprecated; use .on("mousewheel", handler).
• .mousewheel(): Triggers the jQuery mousewheel event. Deprecated helper syntax.
• .unmousewheel(handler): Removes a handler registered through the helper API. Deprecated; use .off("mousewheel", handler).

// Deprecated helper syntax.
$("#wheel-demo").mousewheel(function(event) {
  console.log(event.deltaY);
});

$("#wheel-demo").unmousewheel();

The older handler arguments delta, deltaX, and deltaY are deprecated. Read normalized delta values from the event object.

jQuery Mousewheel vs Native wheel Event

jQuery Mousewheel	Native wheel Event
Requires jQuery.	Uses the browser's DOM event API.
Dispatches mousewheel.	Dispatches wheel.
Normalizes deltaX and deltaY to whole steps.	Reports native device and browser delta values.
Adds deltaFactor.	Does not define deltaFactor.
Uses the legacy vertical delta sign.	Uses the native WheelEvent sign.

Native wheel is the direct browser API for projects that do not otherwise need jQuery. jQuery Mousewheel serves jQuery code that expects the mousewheel event or its normalized delta behavior.

Native wheel Example

var element = document.getElementById("wheel-demo");

element.addEventListener("wheel", function(event) {
  console.log(event.deltaX, event.deltaY, event.deltaMode);
});

Changelog

v3.2.2

• Includes the minified file in the npm package.

v3.2.0

• Uses .on() and .off() for event binding where those methods are available.
• Preserves mouse offset properties when the plugin does not adjust them.
• Removes the obsolete Bower version property and executable bit from the library file.
• Updates browser tests and lint tooling.

v3.1.13

• Updates copyright and license text.
• Corrects the compressed build.
• Removes the obsolete jQuery Plugin Registry file.

v3.1.10

• Improves line-height calculations with older jQuery versions.
• Adds offsetX and offsetY normalization with a setting to disable it.
• Cleans up plugin data during teardown.

v3.1.9

• Improves handling of older wheel deltas based on values divisible by 120.
• Adds adjustOldDeltas for disabling that adjustment.

v3.1.6

• Moves normalized deltaX and deltaY values onto the event object.
• Adds event.deltaFactor.
• Deprecates the separate delta, deltaX, and deltaY handler arguments.
• Improves handling of small deltas and mixed input devices.

v3.1.0

• Uses the wheel event in Firefox 17 and later.
• Normalizes delta values.
• Adds horizontal wheel support for IE 9 and later through the wheel event.
• Adds AMD loader support.

---

This awesome jQuery plugin is developed by jquery. For more Advanced Usages, please check the demo page or visit the official website.