Have ideas to improve npm?Join in the discussion! »

    lethargy

    1.0.9 • Public • Published

    Lethargy

    CDNJS FOSSA Status

    Lethargy is a tiny (612b minified + gzipped) JavaScript library to help distinguish between scroll events initiated by the user, and those by inertial scrolling. Lethargy does not have external dependencies.

    Lethargy is used in smartscroll, a jQuery scroll plugin, to resolve problems with inertial scrolling.

    Demo

    Install

    Download lethargy.js or lethargy.min.js

    Bower

    bower install lethargy
    

    npm

    npm install lethargy
    

    Use

    Include lethargy.min.js in your document.

    <script src="./lethargy.js"></script>
    

    Create an instance of Lethargy. You may pass in options (see below), but usually the default is good enough.

    var lethargy = new Lethargy(); // Use defaults
    var lethargy = new Lethargy(7, 100, 0.05); // Tinkering with the options
    

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

    Bind the mousewheel or scroll events and pass the event to Lethargy.

    $(window).bind('mousewheel DOMMouseScroll wheel MozMousePixelScroll', function(e){
        e.preventDefault()
        e.stopPropagation();
        if(lethargy.check(e) !== false) {
            // Do something with the scroll event
        }
    });
    

    lethargy.check(e) will return 1 if it is a normal scroll up event, -1 if it is a normal scroll down event, and false if it is 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).

    Webpack

    If you are using Webpack, you can use the exports-loader to require the Lethargy constructor.

    $ yarn add exports-loader
    

    Then, to import Lethargy:

    const Lethargy = require("exports-loader?this.Lethargy!lethargy/lethargy");
    

    Options

    All options are optional.

    MacBook Air Trackpad  curve

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

    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.

    Below charts the wheelDelta values of each scroll action using this Gist and demo by Matthew Simpson.

    Desktop Mouse

    Desktop Mouse  graph

    MacBook Air Trackpad

    MacBook Air Trackpad  curve

    As you can see, the Desktop Mouse emits small

    How does it work?

    Lethargy keeps a record of the last few wheelDelta values that is 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, and so our method of decay detection would not work. Instead, to cater for this situation, we had to, grudgingly, set a very small time delay between when events will register. We have tested this and for normal use does not affect user experience more than usual.

    ASUS Trackpad

    ASUS Trackpad

    License

    FOSSA Status

    Install

    npm i lethargy

    DownloadsWeekly Downloads

    5,506

    Version

    1.0.9

    License

    MIT

    Unpacked Size

    25.8 kB

    Total Files

    13

    Last publish

    Collaborators

    • avatar