JavaScript Element wheel Event

What You’ll Learn

The wheel event fires when the user rotates a mouse wheel or a related device (trackpad, mouse ball). Learn addEventListener vs onwheel, WheelEvent deltas, passive listeners, how it differs from scroll, custom zoom with preventDefault, and five try-it labs.

Introduction

wheel answers: “Did the user turn a wheel or trackpad?” That is an input intent signal—not a guarantee that content scrolled. It is also the modern replacement for the obsolete mousewheel event.

Zooming with Ctrl + wheel / trackpad pinch often fires wheel with ctrlKey set to true. Canceling the event can block scrolling or zooming, but blocking every wheel can hurt scroll performance—prefer { passive: true } when you only listen.

Understanding wheel

An instance event that answers: “Did a pointing device report a wheel-like rotation over this element?”

• Trigger — mouse wheel, trackpad scroll gesture, or similar.
• Event type — WheelEvent with deltaX, deltaY, deltaZ, deltaMode.
• Bubbles — yes; can be listened for on ancestors.
• Cancelable — yes (sometimes only the first event in a sequence).
• Limited availability on MDN (not Baseline)—notably missing on Safari iOS.

📝 Syntax

Use the event name with addEventListener, or set the handler property:

addEventListener("wheel", (event) => { });

onwheel = (event) => { };

Event type

A WheelEvent (inherits from MouseEvent, UIEvent, and Event).

Handy WheelEvent properties

deltaMode constants

⚖️ wheel vs Related Signals

⚡ Passive Listeners & Cancelability

Canceling wheel (via preventDefault()) can stop scrolling or zooming. MDN notes that in some browsers only the first wheel event in a sequence is cancelable. Waiting on every wheel handler before scrolling can cause jank.

• Observing only? Use addEventListener("wheel", fn, { passive: true }).
• Need to cancel (custom zoom, custom scroll)? Use { passive: false } and call preventDefault() carefully.
• Keep handlers light—wheel can fire at a high rate on trackpads.

Examples Gallery

Examples follow MDN Element: wheel event. Use a mouse wheel or trackpad over each try-it lab.

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

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

wheel deltaY=100.0

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

pad.onwheel = (event) => {
  out.textContent = "onwheel fired (deltaY=" + event.deltaY.toFixed(1) + ")";
};

onwheel fired (deltaY=-40.0)

const pad = document.getElementById("pad");
const out = document.getElementById("out");
const modes = ["PIXEL", "LINE", "PAGE"];

pad.addEventListener("wheel", (event) => {
  out.textContent =
    "dx=" + event.deltaX.toFixed(1) +
    " dy=" + event.deltaY.toFixed(1) +
    " mode=" + (modes[event.deltaMode] || event.deltaMode);
}, { passive: true });

dx=0.0 dy=100.0 mode=PIXEL

let scale = 1;
const el = document.querySelector("#zoom-box");

function zoom(event) {
  event.preventDefault();
  scale += event.deltaY * -0.01;
  scale = Math.min(Math.max(0.125, scale), 4);
  el.style.transform = "scale(" + scale + ")";
}

el.addEventListener("wheel", zoom, { passive: false });

Box scales between 0.125× and 4× as you wheel over it

const box = document.getElementById("scroll-box");
const out = document.getElementById("out");
const log = [];

function push(msg) {
  log.unshift(msg);
  out.textContent = log.slice(0, 6).join("\n");
}

box.addEventListener("wheel", () => push("wheel"), { passive: true });
box.addEventListener("scroll", () => {
  push("scroll top=" + Math.round(box.scrollTop));
});

scroll top=48
wheel
scroll top=24
wheel

🚀 Common Use Cases

• Custom zoom / scale for maps, canvases, and image viewers.
• Detecting trackpad / wheel intent before content scrolls.
• Horizontal gallery navigation when deltaX dominates.
• Teaching tools that visualize input deltas for beginners.
• Migrating from deprecated mousewheel to standard wheel.

🔧 How It Works

📝 Notes

• MDN: Limited availability (not Baseline)—no Deprecated / Experimental / Non-standard banner.
• Safari on iOS generally does not support Element wheel.
• Prefer { passive: true } unless you must call preventDefault().
• Do not use delta* as the source of truth for scroll direction.
• Related learning: scroll, scrollend, mousewheel, addEventListener(), JavaScript hub.

💡 Best Practices