simplesmoothscroll

    2.0.3 • Public • Published

    simplesmoothscroll

    npm version Build Status

    A module to simply scroll to an element on the page in a buttery smooth fashion

    • No dependencies
    • CommonJS, AMD, and Browser ready

    DEMO!

    What is it?

    Simple smooth scroll takes in a dom element and scrolls to that element in an ease-in-out fashion. It can work on elements that are above the current window position or below the current window position

    Installation

    npm install simplesmoothscroll --save

    Usage

    var smoothScroll = require("simplesmoothscroll");
     
    // Passing in no params scrolls you to the top of the page
    smoothScroll();
     
    // Passing an element as a param scrolls you to that element
    var myHeader = document.querySelector("h2");
    smoothScroll(myHeader);
     
    // You can also include an offset so there is some room between
    // the top of the viewport and the element
    smoothScroll(myHeader, {
      offset: 10
    });
     
    /**
     *  If you want to execute a function when the scroll finishes, you can
     *  pass in an onScrollFinished callback. A "cancelled" param is passed in
     *  as an arg in case the scroll was cancelled due to user interaction
     */
    smoothScroll(myHeader, {
      offset: 10,
      onScrollFinished: function(cancelled) {
        // Your function
      }
    });
     
    /**
     * If you want your own easing function instead of the default trig-based
     * ease-in-out function, you can pass in a getEasingFunction parameter that
     * should return your custom easing function. "getEasingFunction" is passed in
     * the targetPosition (distance the target is from the viewport)
     * and the returned function will be passed a "stepCount" argument that
     * represents the number of frames since the scroll started.
     * The easing function should return a value between 0 and 1 where 0
     * will scroll to the initial position and 1 will scroll to the target.
     * Below is an example of using a custom linear scroll
     */
    smoothScroll(myHeader, {
      getEasingFunction: function(targetPosition) {
        return function(stepCount) {
          return stepCount * 0.01;
        };
      }
    });

    API

    smoothScroll(element, options)

    • element [optional] - a dom element to scroll to. If not provided, smoothScroll will scroll to the top of the page
    • options [optional] - option parameters for the smooth scroll
      • offset - A margin between the target element and the top of the viewport
      • onScrollFinished - A function to execute when the scroll finishes. It is passed a "cancelled" argument in case the scroll did not finish due to user interaction with the page.
      • getEasingFunction - A function that should return your custom easing function if you do not wish to use the default easing function. This is passed in a targetPosition argument. See usage for an example

    Contributing

    My goal here is to make the scroll as performant and smooth as possible. If there are optimizations that can be made then feel free to open an issue or submit a pull request.

    License

    Released under the MIT License

    Install

    npm i simplesmoothscroll

    DownloadsWeekly Downloads

    175

    Version

    2.0.3

    License

    MIT

    Unpacked Size

    188 kB

    Total Files

    21

    Last publish

    Collaborators

    • jljorgenson18