DOM & EventsBaseline · Widely

Passive Event Listeners and Compositor Scrolling

Mental Model

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.

Interactive Simulator

Blocking Touch/Wheel Listener vs { passive: true }

Lines of Code
Before
3
After
3
Reflows / Browser Cost
Before
Main-thread sync gate
After
0ms compositor wait
BeforeNon-Passive Listener (Blocks Compositor)
carousel.addEventListener('touchmove', (e) => {
  trackSwipeAnalytics(e.touches[0].clientX);
}); // Compositor waits on main thread every frame
Lines: 3Reflows: Main-thread sync gateDependencies: Scroll jank under load

Compositor stalls scroll until JS returns and confirms no preventDefault().

After (Native)Passive Listener ({ passive: true })
carousel.addEventListener('touchmove', (e) => {
  trackSwipeAnalytics(e.touches[0].clientX);
}, { passive: true }); // Compositor scrolls immediately
Lines: 3Reflows: 0ms compositor waitDependencies: 60/120fps scroll thread

Compositor 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.

  1. 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.
  2. Passive Fast Path: The compositor translates the layer immediately and dispatches the event asynchronously.
  3. Root Default: Chrome, Firefox, and Safari default touchstart, touchmove, and wheel on window, document, and body to passive: true.
JS
// 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 touchstart listener 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* and wheel listeners to passive by default.

Production Pitfalls

Production Pitfall
  • Ignored preventDefault() on document: Calling e.preventDefault() inside a document-level wheel listener logs a warning and fails to stop scrolling unless { passive: false } is set.
  • Third-Party Tracking Scripts: Non-passive touchstart listeners attached to inner containers silently re-introduce scroll jank.
When Not to Use
  • When not to use { passive: false }: Avoid { passive: false } on general page wrappers just to suppress scroll conditionally; use CSS touch-action via Pointer Events & touch-action instead.

Connections & Logical Next Steps

Seen in Architecture Autopsies

Mechanical Comparisons