HTML onwheel Attribute

Introduction

The onwheel attribute is the standard inline event handler for the wheel event. It runs JavaScript when the user turns a mouse wheel, scrolls a trackpad, or performs a similar scroll gesture over an element. Pass event to the handler and read event.deltaY (vertical scroll amount; positive usually means scroll down). Use it for custom zoom, font-size controls, image carousels, or logging scroll direction. It is not the same as onscroll (position changed) or legacy onmousewheel (non-standard). Prefer addEventListener("wheel", …) in production.

What You’ll Learn

Purpose of onwheel Attribute

The primary purpose of onwheel is to run custom JavaScript when a wheel gesture happens over an element — before or instead of default scrolling. Maps, image viewers, and design tools often use the wheel event for zoom and pan.

The handler receives a WheelEvent with deltaY, deltaX, and deltaMode. You can react to direction, adjust UI values, or call event.preventDefault() to block default scroll (only when necessary, and with { passive: false } when using addEventListener).

📝 Syntax

Set onwheel on any element, or assign element.onwheel in JavaScript:

<div onwheel="handleWheel(event)" tabindex="0">
  Scroll wheel here
</div>

<script>
  box.onwheel = handleWheel;
  box.addEventListener("wheel", handleWheel);
</script>

Syntax Rules

• Value is JavaScript executed when the wheel event fires.
• Pass event to read deltaY, deltaX, deltaMode.
• Works on most elements — div, p, canvas, etc.
• Add tabindex="0" on non-interactive elements so they can receive focus in demos.
• Not the same as onscroll (fires when scroll position changes).
• Also assignable as element.onwheel in script.
• Modern alternative: el.addEventListener("wheel", handler).
• For preventDefault(), use addEventListener("wheel", fn, { passive: false }).

💎 Values

The onwheel attribute accepts a string of JavaScript code:

• onwheel="handleWheel(event)" — Call a named function with the event object.
• onwheel="status.textContent = event.deltaY" — Inline update.
• JavaScript: box.onwheel = (e) => { … } — property assignment.

function handleWheel(event) {
  if (event.deltaY > 0) {
    status.textContent = "Scrolled down (deltaY: " + event.deltaY + ")";
  } else if (event.deltaY < 0) {
    status.textContent = "Scrolled up (deltaY: " + event.deltaY + ")";
  }
}

Applicable Elements

onwheel vs onmousewheel vs onscroll

Examples Gallery

Change font size with wheel, dynamic assignment, and a zoom counter with addEventListener.

<p id="scrollText" onwheel="changeFontSize(event)">
  Scroll to change font size!
</p>
<p id="status">Font size: 16px</p>

<script>
  function changeFontSize(event) {
    var el = document.getElementById("scrollText");
    var size = parseFloat(getComputedStyle(el).fontSize);
    if (event.deltaY < 0) size += 2;
    else if (event.deltaY > 0) size -= 2;
    size = Math.max(12, Math.min(32, size));
    el.style.fontSize = size + "px";
    document.getElementById("status").textContent = "Font size: " + size + "px";
  }
</script>

<div id="dynamicElement" tabindex="0">Scroll wheel here</div>

<script>
  document.getElementById("dynamicElement").onwheel = function (event) {
    log.textContent = "Wheel detected — deltaY: " + event.deltaY;
  };
</script>

var zoom = 100;

box.addEventListener("wheel", function (event) {
  if (event.deltaY < 0) zoom += 10;
  else if (event.deltaY > 0) zoom -= 10;
  zoom = Math.max(50, Math.min(200, zoom));
  box.textContent = zoom + "%";
  box.style.transform = "scale(" + (zoom / 100) + ")";
});

♿ Accessibility

• Do not trap scroll — Avoid preventDefault() on wheel unless necessary; it blocks normal page scroll.
• Provide keyboard alternatives — +/- keys or buttons for zoom when wheel-only controls exist.
• Respect reduced motion — Check prefers-reduced-motion before wheel-driven animations.
• Focusable targets — Add tabindex="0" if a non-interactive div must receive wheel focus for demos.
• Touch users — Wheel events are pointer-driven; offer pinch or button controls on touch devices.

💡 Best Practices