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.
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
Syntax
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
scrollevent on an element does not bubble. A page scroll fires ondocumentand bubbles towindow, so listen onwindowordocumentfor 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
IntersectionObserverinstead 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 withsetTimeout(). Check a compatibility table before relying on it.- Cancelling. You cannot cancel
scroll; it has already happened. To stop scrolling, cancel thewheelortouchmoveevent, or set CSSoverflow: hiddenoroverscroll-behavior. - Passive by default. Browsers treat
wheellisteners onwindow,documentandbodyas passive, sopreventDefault()is ignored there unless you pass{ passive: false }. See passive listeners. - Do not rely on
deltaYsize. Values differ between devices and browsers. Use only the sign, or scale it yourself. - Programmatic scrolling fires
scrolltoo, includingscrollTo()andscrollIntoView().
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.
Related
- passive listeners โ why
wheelandtouchmoveneed{ passive: false } window.scrollTo()and scroll positionIntersectionObserverElement.scrollIntoView()- touch and gesture events
- Lesson: Events