Touch and wheel event listeners are useful for tracking user interactions and creating custom scrolling experiences, but they can also delay page scrolling. Currently, browsers can't know if an event listener will prevent scrolling, so they always wait for the listener to finish executing before scrolling the page. Passive event listeners solve this problem by letting you indicate that an event listener will never prevent scrolling.
Browser compatibility
Most browsers support passive event listeners. See Browser compatibility
How the Lighthouse passive event listener audit fails
Lighthouse flags event listeners that may delay page scrolling:
Lighthouse uses the following process to identify event listeners that may affect scrolling performance:
- Collect all event listeners on the page.
- Filter out non-touch and non-wheel listeners.
- Filter out listeners that call
preventDefault(). - Filter out listeners that are from a different host than the page.
Lighthouse filters out listeners from different hosts because you probably don't have control over these scripts. There may be third-party scripts that are harming your page's scrolling performance, but these aren't listed in your Lighthouse report.
How to make event listeners passive to improve scrolling performance
Add a passive flag to every event listener that Lighthouse identified.
If you're only supporting browsers that have passive event listener support, just add the flag. For example:
document.addEventListener('touchstart', onTouchStart, {passive: true});
If you're supporting older browsers that don't support passive event listeners, you'll need to use feature detection or a polyfill. See the Feature Detection section of the WICG Passive event listeners explainer document for more information.