Passive Event Listeners and Compositor Scrolling
Passing { passive: true } to addEventListener guarantees your wheel or touchmove handler will never call preventDefault(). That promise lets GPU Compositor Layers scroll immediately on the compositor thread instead of stalling DOM Event Propagation on a busy main thread.
Blocking Touch/Wheel Listener vs { passive: true }
carousel.addEventListener('touchmove', (e) => {
trackSwipeAnalytics(e.touches[0].clientX);
}); // Compositor waits on main thread every frameCompositor stalls scroll until JS returns and confirms no preventDefault().
carousel.addEventListener('touchmove', (e) => {
trackSwipeAnalytics(e.touches[0].clientX);
}, { passive: true }); // Compositor scrolls immediatelyCompositor translates layers immediately; JS runs asynchronously.
Under the Hood
The compositor thread checks a hit-tested layer's non-passive event region bit before translating a scroll gesture; if any non-passive touchstart or wheel listener is present, scrolling stalls until main-thread JS finishes. Passing { passive: true } gives the compositor permanent clearance to translate the layer immediately at 120 fps.
- Non-Passive Slow Path: The compositor checks a "slow scroll region" bit; if present, it waits for main-thread JS to finish running the listener before scrolling.
- Passive Fast Path: The compositor translates the layer immediately and dispatches the event asynchronously.
- Root Default: Chrome, Firefox, and Safari default
touchstart,touchmove, andwheelonwindow,document, andbodytopassive: true.
// Analytics listener: never blocks compositor scroll
scroller.addEventListener('wheel', recordScrollDelta, { passive: true });
// Custom zoomable map: explicitly opt out of passive
mapCanvas.addEventListener('wheel', (e) => {
e.preventDefault();
zoomMap(e.deltaY);
}, { passive: false });Problem Genealogy
- 2012 (Touch Scroll Jank): Any
touchstartlistener forced mobile browsers to block scrolling on main-thread JS execution. - 2016 (
{ passive: true }Option): Added explicit opt-in for non-canceling scroll and touch listeners. - 2017–2019 (Root Passive Defaults): Browsers flipped document-level
touch*andwheellisteners to passive by default.
Production Pitfalls
- Ignored
preventDefault()ondocument: Callinge.preventDefault()inside a document-levelwheellistener logs a warning and fails to stop scrolling unless{ passive: false }is set. - Third-Party Tracking Scripts: Non-passive
touchstartlisteners attached to inner containers silently re-introduce scroll jank.
- When not to use
{ passive: false }: Avoid{ passive: false }on general page wrappers just to suppress scroll conditionally; use CSStouch-actionvia Pointer Events &touch-actioninstead.
Connections & Logical Next Steps
CSS touch-action negotiates scroll ownership on the compositor without blocking passive listeners.
Passive flags are checked during hit-testing before dispatching wheel or touch propagation.
Without passive listeners, the GPU compositor thread must stall scroll translation on main-thread JS.
Passive listeners promise no preventDefault() in JS, whereas CSS touch-action declares scroll constraints to the compositor.