CKTIS / JavaScript
`scroll` and `resize` events and the `passive` option
Choose the right target for scroll and resize notifications, and learn when a passive listener changes whether you can cancel a default action.
Version: Current web platform; runtime support varies
Syntax
// ECMAScript 2024 identifies the JavaScript language reference, not the version of these browser APIs.
// The DOM Standard defines the passive listener option, CSSOM View defines scroll and resize,
// and the Resize Observer specification defines ResizeObserver.
document.addEventListener("scroll", onPageScroll);
scrollContainer.addEventListener("scroll", onElementScroll);
window.addEventListener("resize", onViewportResize);
scrollContainer.addEventListener("wheel", onWheel, { passive: true });
scrollContainer.removeEventListener("wheel", onWheel);
const observer = new ResizeObserver(onElementResize);
observer.observe(element);
// When observation is no longer needed:
observer.disconnect();Listen for scroll on document for page scrolling or directly on the scrolling element for changes inside a container. scroll reports a position change, whether it came from the user or from code. wheel reports input and does not necessarily cause scrolling. Listen for resize on window when the viewport changes size; this event does not bubble. Use ResizeObserver to watch an element's size instead.
Pass { passive: true } in the options object as the third argument to addEventListener(); a bare boolean there sets capture, not passive. In a passive listener, preventDefault() has no effect and may produce a warning. { passive: false } allows cancellation of the default action only if event.cancelable is true. Browser-generated document or element scroll events and window resize events are not cancelable; the option does not change that.
For input such as wheel or touchmove, a passive listener lets the browser start scrolling without waiting for that listener to finish. When you omit the option, the default can depend on the event, target, and browser. Set passive: true when you only observe the input. If you need to cancel the action, set passive: false and check event.cancelable.
passive neither reduces the callback rate nor makes the callback's work cheaper. Keep handlers for frequent events short; if expensive work needs to run less often, throttle it with a timer. requestAnimationFrame() helps align visual updates with frames but does not by itself guarantee a lower rate than scroll.
For cleanup, call removeEventListener() on the same target with the same type, callback, and capture value; passive is not part of the match. These APIs belong to the web platform, not ECMAScript 2024. Check support in your target runtime.
Examples
{
const cases = [
["scroll", false, false],
["resize", false, false],
["wheel", true, true],
["wheel", true, false],
];
for (const [type, cancelable, passive] of cases) {
const target = new EventTarget();
target.addEventListener(type, (event) => event.preventDefault(), { passive });
const event = new Event(type, { cancelable });
target.dispatchEvent(event);
console.log(`${type} cancelable=${event.cancelable} passive=${passive} defaultPrevented=${event.defaultPrevented}`);
}
}Result
scroll cancelable=false passive=false defaultPrevented=false resize cancelable=false passive=false defaultPrevented=false wheel cancelable=true passive=true defaultPrevented=false wheel cancelable=true passive=false defaultPrevented=true
Run this in a browser console. The synthetic events do not scroll the page or resize the window. Only the last case sets `defaultPrevented` to `true`: the event is cancelable and the listener is not passive. The passive cancellation attempt may produce a separate warning.
Related lessons
- JavaScript · Lesson 11 · Advanced · Version: 4
Sources
- Document: scroll event
- Element: scroll event
- Window: resize event
- ResizeObserver
- EventTarget: addEventListener() method
- EventTarget: removeEventListener() method
- Event: preventDefault() method
- Element: wheel event
- Event: Event() constructor
- EventTarget: dispatchEvent() method
- HTML Standard: Processing model
- ECMAScript 2024 Language Specification: Hosts and Implementations