Skip to content
Tutorials Center
My learning

Topics

JavaScript Reference ยท DOM: Events

The scroll and wheel events

Reference for the scroll, scrollend and wheel events: read scroll positions, throttle handlers with requestAnimationFrame, and understand passive wheel listeners.

Two different events describe movement through a page. The scroll event tells you that an element or the page has already scrolled, whatever the cause: the mouse wheel, the keyboard, a scrollbar drag, a touch swipe or a script. The wheel event tells you that the user turned a wheel or used a touchpad gesture; it fires before the scroll happens and can be cancelled to stop it.

Use scroll to react to a position (a progress bar, a "back to top" button). Use wheel only when you want to take over the wheel's meaning, for example to zoom a canvas.

JavaScript
box.addEventListener("scroll", () => {
  console.log(box.scrollTop);
});

canvas.addEventListener("wheel", (event) => {
  event.preventDefault();       // needs { passive: false }
  zoom += event.deltaY * -0.001;
}, { passive: false });

Try it

A reading progress bar driven by scroll
Taking over the wheel

Syntax

JavaScript
target.addEventListener("scroll", listener);
target.addEventListener("scrollend", listener);
target.addEventListener("wheel", listener, { passive: false });

Useful properties

Name Description
element.scrollTop, element.scrollLeft How far the element's content is scrolled, in CSS pixels (may be fractional).
element.scrollHeight, element.clientHeight Total content height and visible height. Their difference is the maximum scrollTop.
window.scrollY, window.scrollX Scroll position of the page.
wheelEvent.deltaX, deltaY, deltaZ Amount scrolled by this wheel step. Positive deltaY means scrolling down.
wheelEvent.deltaMode Unit of the deltas: 0 pixels, 1 lines, 2 pages.
wheelEvent.ctrlKey true for pinch-to-zoom gestures on many touchpads, and for Ctrl + wheel.

The scroll event is not cancelable. The wheel event is cancelable (unless the listener is passive).

Usage notes

  • Where it fires. A scroll event on an element does not bubble. A page scroll fires on document and bubbles to window, so listen on window or document for it. To catch scrolls from many elements at once, add the listener with { capture: true }.
  • It runs often. Do not do layout reads or heavy work on every event. Set a flag and do the work in requestAnimationFrame(), as in the first example.
  • Prefer observers. To know when an element enters the viewport, use IntersectionObserver instead of measuring in a scroll handler. For scroll-linked animation, CSS scroll-driven animations avoid JavaScript entirely.
  • scrollend. This newer event fires once when scrolling has finished, which is better than debouncing with setTimeout(). Check a compatibility table before relying on it.
  • Cancelling. You cannot cancel scroll; it has already happened. To stop scrolling, cancel the wheel or touchmove event, or set CSS overflow: hidden or overscroll-behavior.
  • Passive by default. Browsers treat wheel listeners on window, document and body as passive, so preventDefault() is ignored there unless you pass { passive: false }. See passive listeners.
  • Do not rely on deltaY size. Values differ between devices and browsers. Use only the sign, or scale it yourself.
  • Programmatic scrolling fires scroll too, including scrollTo() and scrollIntoView().

Browser support

scroll and wheel work in every browser. scrollend is newer and not available everywhere yet, so check a compatibility table and keep a fallback.