Use passive listeners to improve scrolling performance

Use passive listeners to improve scrolling performance

Appears in: Best Practices audits

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 audit shows page doesn't use passive event listeners to improve scrolling performance

Lighthouse uses the following process to identify event listeners that may affect scrolling performance:

  1. Collect all event listeners on the page.
  2. Filter out non-touch and non-wheel listeners.
  3. Filter out listeners that call preventDefault().
  4. 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.

Each Best Practices audit is weighted equally in the Lighthouse Best Practices Score. Learn more in The Best Practices score.

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.

Resources #

Last updated: Improve article