1.1.6 • Public • Published

    Issues MIT License LinkedIn


    🖱️ smooth-scrollr

    Simple smooth scrolling module based on fake scroll events (aka wheel and touch and keyPress...).

    View Demos · Report Bug · Request Feature

    Table of Contents

    1. About The Project
    2. Getting Started
    3. Usage
    4. Roadmap
    5. Who is Using
    6. Contributing
    7. License
    8. Contact

    About The Project

    Built With

    Getting Started

    Made as a prototype reveal based class, initialize the module to use it.


    This is an example of how to list things you need to use the software and how to install them.

    • npm

      npm i smooth-scrollr@latest
    • yarn

      yarn add smooth-scrollr


    1. Clone the repo
      git clone
    2. Install NPM packages
      npm install


    Basic usage :

    <main class="" id="section">
        <section class="" data-scroll-container>
            <article class=""></article>
            <article class=""></article>
            <article class=""></article>
        <section class="" data-scroll-container>
            <article class=""></article>
            <article class=""></article>
            <article class=""></article>

    Note: data-scroll-container are optional but recommended to improve long page performance.

    import { SmoothScrollr } from 'smooth-scrollr';
    const opts = {
      section: document.querySelector('#section'),
      speed: .8,
      fixedClass: 'fixedClass'
    const smoothscroll = new SmoothScrollr(opts);

    Note: 'fixedClass' is optional and set the class you define to block real scroll to the right container. Inline styles are used if not definied

    ...Or in a global way (without bundler)

    Get the smooth-scrollr.min.js file inside the dist folder. Then, use it in the html file :

    <script src="smooth-scrollr.min.js"></script>
        (function () {
            const opts = {/*opts here */};
            var scroll = new SmoothScrollr(opts);

    Options and Settings

    Option Type Default Description
    section object body DOM section that you want to make scrollable or data-scroll-containers parent if you want to use multi wrapper option (make sure the parent wrap all children in horizontal scroll case).
    direction string vertical vertical
    speed number 1 Speed value on the range 0-1 that is slowing the smoothing effect.
    delay number .1 Easing value between 0 & 1
    fixedClass string The class you want to set in order to fix the viewport (at least you need overflow: hidden and height: 100% on the container and overscroll-behavior: none or overflow: hidden on the body).
    touch boolean false Enable smooth scroll on touch event
    touchSpeed number 1.5 Scrolling speed on touch event
    jump number 110 Scrolling step on keyPress event
    multFirefox number 15 Scrolling speed on Firefox
    preload boolean true Enable preload media function in order to resize page after async
    resize boolean true Enable auto resize
    initFuncs array Array of functions that must be fired after the instance has been initialised. If preload, init takes place after the event

    Element attribute

    • data-scroll-container : create a scrollable container inside the section. Splitting the page into smaller container is good to improve performance. Only the viewed container will move, so lighten containers will move one after the other. This is totaly optional.


    Methods Description Arguments
    scrollTo In order to force scroll to a location on the webpage. dir : (number) - the position in px you want to go on the page
    - imediate : (boolean - default: false) - go with/without smooth effect
    scrollOf In order to scroll from a specific number of pixel. path : (number) - the distance in px you want the page go through. Return the scroll position
    - imediate : (boolean - default: false) with/without smooth effect
    getSize In order to get the scroller container size.
    on In order to add a listener function on a specific scroll event. event : (string) - the instance event you want to listen (see the list below)
    callback : (function) - the function you want to trigger when the event is dispatched
    context : (object - default : section) the content you want to listen (you should avoid to use it unless you know what you do)
    off In order to remove a listener function on a specific scroll event. event : (string) - the instance event you want to remove a listener (see the list below)
    callback : (function) - the function you want to remove (use the same as you set to add the listener)
    context : (object - default : section) the content you want to listen (you should avoid to use it unless you know what you do)
    resize In order to recalculate scroll container.
    destroy In order to destroy scroll container.
    preventScroll In order to freeze scrolling movement. state : (boolean) - freeze or unfreeze scroll event

    Exemples :

    Force imediate scroll

    smoothscroll.scrollTo(0, true); // go to the top without smoothing

    Smooth scroll of 200px

    smoothscroll.scrollFrom(200, false); // go 200px forward smoothly

    Add a callback to scroll instance event

    const callback = () => { console.log('yeah!!')}
    smoothscroll.on('scroll', callback); // 'yeah!!` appears in the console during the scroll.
    // You can access scroll position as parameter in callbak function (scroll event only)

    Remove a callback to scroll instance event'scroll', callback); // use the same previous callback function

    Destroy scroll instance

    smoothscroll.destroy(); // all events are removed and the instance has been killed


    Event Description
    scroll trigger during scroll
    collisionTop trigger when the scroll is at top of the page
    collisionBottom trigger when the scroll is at bottom of the page
    collisionEnded trigger once when the scroll stop to be blocked by the collision with page edges


    • [x] ScrollTo method
    • [x] destroy method
    • [x] horizontal scroll support
    • [ ] add a scroll bar

    Who is Using


    Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are appreciated.

    1. Fork the Project
    2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
    3. Commit your Changes (git commit -m 'Add some AmazingFeature')
    4. Push to the Branch (git push origin feature/AmazingFeature)
    5. Open a Pull Request


    Distributed under the MIT License. See LICENCE FILE for more information.


    Alexis Colin - linkedin -

    Project Link:


    npm i smooth-scrollr

    DownloadsWeekly Downloads






    Unpacked Size

    83.7 kB

    Total Files


    Last publish


    • alexiscolin