Smooth Scrollbar

Customizable, High Performance, and Full of Features Scrollbars!

View on Github
Version:

Why smooth-scrollbar?

  • If you want smooth scrolling, use smooth-scrollbar;
  • If you want customizable scrollbars, use smooth-scrollbar;
  • If you want high-performance scrollbars, use smooth-scrollbar;
  • If you want incredibly prompt user support, use smooth-scrollbar;
  • If you want perfect scrollbar in modern browsers, use smooth-scrollbar!

So, why would you still use other scrollbar plugins? All you need is a quick setup:

Install

Via npm:

npm install smooth-scrollbar --save

Via bower:

bower install smooth-scrollbar --save

Browser Compatibility

Browser Version
IE 10+
Chrome 22+
Firefox 16+
Safari 8+
Android Browser 4+
Chrome for Android 32+
iOS Safari 7+

Why is native scrolling slow?

As is explained in this article, browser repaint every frame in scrolling. Less painting is better.

To avoid repainting, I use translate3d in scroll content to create composite layers and force hardware accelerating.

Usage

Smooth scrollbar is defined as an UMD module which named Scrollbar, you can use any loader to load it:

import Scrollbar from 'smooth-scrollbar';

Or get it from window object:

const { Scrollbar } = window;

Don't forget to include the stylesheet in your page:

<link rel="stylesheet" href="dist/smooth-scrollbar.css">

Here're three ways to tell the plugin which element should be a smooth scrollbar:

  1. As an element:
    <scrollbar>
        ...
    </scrollbar>
  2. As an attribute:
    <section scrollbar>
        ...
    </section>
  3. As a data-attribute:
    <section data-scrollbar>
        ...
    </section>

Then init all scrollbars:

Scrollbar.initAll(options);

Or you can call Scrollbar.init(elem, options) to manually init the scrollbar.

Available Options for Scrollbar

parameter type default description
speed Number 1 Scrolling speed scale.
damping Number 0.1 Delta reduce damping, a float value between (0, 1), the lower the value is, the more smooth the scrolling will be.
thumbMinSize Number 20 Minimal size for scrollbar thumb.
renderByPixels Boolean true Render scrolling by integer pixels, set to true to improve performance.
alwaysShowTracks Boolean false Keep scrollbar tracks visible whether it's scrolling or not.
continuousScrolling Boolean|String 'auto' Whether allow upper scrollable content to continue scrolling when current scrollbar reaches edge. When set to 'auto', it will be enabled on nested scrollbars, and disabled on first-class scrollbars.
overscrollEffect Boolean|String false Experimental overscroll effect, 'bounce' for iOS style effect and 'glow' for Android style effect. Be careful when you enable this feature!
overscrollEffectColor String '#87ceeb' Canvas paint color with 'glow' effect.

DOM Structure

Following is the DOM structure that Scrollbar generated:

<scrollbar>
    <article class="scroll-content">
        your contents here...
    </article>
    <aside class="scrollbar-track scrollbar-track-x">
        <div class="scrollbar-thumb scrollbar-thumb-x"></div>
    </aside>
    <aside class="scrollbar-track scrollbar-track-y">
        <div class="scrollbar-thumb scrollbar-thumb-y"></div>
    </aside>
</scrollbar>

Documents

Check Wiki page here.

Demo

Okay, Let's try it:

<section data-scrollbar>
    <img src="xxx.jpg">
</section>

<script> Scrollbar.initAll(); </script>

Wow, it works! Now change options' value in the controll panel and see what will happen :), be careful that this may affect all scrollbars, aha!