JavaScript Element wheel Event

Beginner
5 min read
Updated: Nov 2026
3 examples
Event
Decorative image with the word WHEEL

Definition

In JavaScript, the wheel event fires when the user rotates a mouse wheel (or a trackpad / device that simulates a wheel). The event type is WheelEvent. It replaces the deprecated non-standard mousewheel event (MDN).

Register a listener with addEventListener. Check readiness and browser support before you rely on this event.

Syntax

Listen for wheel. Start with this line.

JavaScript
el.addEventListener("wheel", fn, { passive: true })
CallWhat it does
el.addEventListener("wheel", fn, { passive: true })Primary signature.

Built into the browser. Listen with el.addEventListener("wheel", …) — no import required.

Library declarations
JavaScript
el.addEventListener("wheel", fn, { passive: true })

Parameters

ParameterDescription
Event targetRequired. Element (or document / window) listening for wheel

Return Value

Return ValueDescription
*Fires as an Element event (listener receives the Event object).

JavaScript Examples

Example 1 — Listen for Wheel

Log when a wheel / trackpad gesture fires. Prefer a passive listener.

JavaScript
const pad = document.getElementById("pad");
const out = document.getElementById("out");

pad.addEventListener("wheel", () => {
  out.textContent = "wheel fired";
}, { passive: true });
Try It Yourself

How It Works

  1. Pick the target. The element that should notice wheel gestures.
  2. Register the listener. The event name is the standard "wheel" string.
  3. Stay passive. { passive: true } lets the browser scroll without waiting.
  4. Try it. Roll the wheel over the pad, or use Simulate in the lab.

Example 2 — Read deltaY

Print vertical wheel delta. Positive often means “down,” but do not treat it as scroll direction truth.

JavaScript
const pad = document.getElementById("pad");
const out = document.getElementById("out");

pad.addEventListener("wheel", (event) => {
  out.textContent = "deltaY=" + event.deltaY;
}, { passive: true });
Try It Yourself

How It Works

  1. Catch the gesture. Each wheel tick sends a WheelEvent.
  2. Read deltaY. Vertical movement amount (units depend on deltaMode).
  3. Do not map to scroll alone. MDN: use scrollTop / scrollLeft on scroll for real direction.
  4. Simulate. Lab buttons inject sample delta values.

Example 3 — Custom Zoom (Cancel Default)

Scale an element with the wheel. Needs passive: false so preventDefault() works.

JavaScript
const box = document.getElementById("box");
const out = document.getElementById("out");
let scale = 1;

box.addEventListener("wheel", (event) => {
  event.preventDefault();
  scale += event.deltaY * -0.01;
  scale = Math.min(Math.max(0.5, scale), 3);
  box.style.transform = "scale(" + scale + ")";
  out.textContent = "scale=" + scale.toFixed(2);
}, { passive: false });
Try It Yourself

How It Works

  1. Opt out of passive. Cancelling needs { passive: false }.
  2. Call preventDefault. Stops the browser from scrolling / zooming that gesture.
  3. Adjust scale. Use deltaY to grow or shrink, then clamp the range.
  4. Apply with JS. Set element.style.transform — no stylesheet required.
Compatibility

Browser Support

Element wheel has Limited availability on MDN (not Baseline). Desktop browsers generally support it; Safari on iOS is a notable gap. It replaces the deprecated non-standard mousewheel event. Prefer scroll when you care about scroll position.

✓ Limited availability

Element wheel

Standard WheelEvent on desktop. Incomplete on some mobile browsers (notably iOS Safari).

Desktop Limited on iOS
Google Chrome Supported
Supported
Mozilla Firefox Supported
Supported
Apple Safari Desktop yes · iOS gap
Partial
Microsoft Edge Supported
Supported
Opera Supported
Supported
Internet Explorer 9+ (legacy)
Partial
wheel Limited

Bottom line: Safe for desktop wheel / trackpad UX. Feature-detect or fall back to scroll / touch on mobile.

Frequently Asked Questions

It fires when the user rotates a wheel button on a pointing device (typically a mouse), or uses related inputs such as a trackpad that simulate wheel actions (MDN). The event type is WheelEvent.
No. MDN does not mark Element wheel as Deprecated, Experimental, or Non-standard. It has Limited availability (not Baseline), mainly because Safari on iOS does not support it. It replaces the deprecated non-standard mousewheel event.
A WheelEvent, which inherits from MouseEvent, UIEvent, and Event. Useful read-only properties include deltaX, deltaY, deltaZ, and deltaMode.
wheel means the user rotated a wheel or trackpad — it may or may not scroll. scroll means the scroll offset actually changed. Zoom gestures can fire wheel with ctrlKey true. Keyboard or scrollbar scrolling can fire scroll without wheel.
No. MDN warns that even when wheel triggers scrolling, delta* values do not necessarily match content scroll direction. Prefer watching scrollLeft / scrollTop on the scroll event.
When you only observe the wheel and do not call preventDefault(). Passive listeners let the browser scroll without waiting on your handler, which avoids jank. Use { passive: false } only when you must cancel the event (for example custom zoom).

Next: addEventListener()

Register wheel and other DOM events with options like passive.

addEventListener() →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

14 people found this page helpful

JavaScript Element webkitmouseforcewillbegin Event JavaScript addEventListener() Method