lethargy-ts

⭐ Lethargy-TS

lethargy-ts is a modern rewrite of lethargy – a popular JavaScript library to help distinguish between scroll events initiated by the user, and those by inertial scrolling.

🌳 Tiny and Easy to use

🦄 Written in TypeScript

🎏 Highly Customizable

🏖 No external dependencies

Install

yarn add lethargy-ts

or

npm install --save lethargy-ts

Usage

Import and create an instance of Lethargy. It will remember previously checked wheelEvents to help to determine if they are inertial or not:

import { Lethargy } from "lethargy-ts";

const lethargy = new Lethargy();

You can customize parameters to better match your application's needs:

const lethargy = new Lethargy({
  stability: 8,
  sensitivity: 100,
  tolerance: 0.1,
  delay: 150,
});

😉 If you found optimizations for the defaults, please share them in this ticket!

Bind the wheel event and pass the event to Lethargy:

const checkWheelEvent = (e: WheelEvent) => {
  const isIntentional = lethargy.check(e);

  if (isIntentional) {
    // Do something with the scroll event
  }
};

window.addEventListener("wheel", checkWheelEvent, { passive: true });

lethargy.check(e) will return true if it's a normal wheel event initiated by the user, and false if it's initiated by inertial scrolling.

Lethargy focus on preventing false positives (saying it's a normal scroll event when it wasn't), but tolerates false negatives (saying it's not a normal scroll event when it is).

Options

All options are optional:

• stability - Specifies the length of the rolling average. In effect, the larger the value, the smoother the curve will be. This attempts to prevent anomalies from firing 'real' events. Valid values are all positive integers, but in most cases, you would need to stay between 5 and around 30.

• sensitivity - Specifies the minimum value for wheelDelta for it to register as a valid scroll event. Because the tail of the curve has low wheelDelta values, this will stop them from registering as valid scroll events. The unofficial standard wheelDelta is 120, so valid values are positive integers below 120.

• tolerance - Prevent small fluctuations from affecting results. Valid values are decimals from 0, but should ideally be between 0.05 and 0.3.

• delay - Threshold for the amount of time between mouse wheel events for them to be deemed separate.

What problem does it solve?

Scroll plugins such as smartscroll, jquery-mousewheel, or fullPage.js work by detecting scroll events and then doing something with them, such as scroll to the next frame. However, inertial scrolling continues to emit scroll events even after the user stopped, and this can often lead to problems, such as scrolling two to three frames when the user only scrolled once.

How does it work?

Lethargy keeps a record of the last few wheelDelta values that are passed through it, it will then work out whether these values are decreasing (decaying), and if so, concludes that the scroll event originated from inertial scrolling, and not directly from the user.

Limitations

Not all trackpads work the same, some trackpads do not have a decaying wheelDelta value, so our method of decay detection would not work. Instead, to cater to this situation, we had to, grudgingly, set a very small time delay between when events will register. We have tested this and normal use does not affect user experience more than usual.

TypeScript

The module is written in TypeScript and type definitions are included.

Contributing

Contributions, issues, and feature requests are welcome!

Show your support

Give a ⭐️ if you like this project!

LICENSE

MIT