Smooth Scrollbar

What is smooth-scrollbar?

Smooth Scrollbar is a JavaScript Plugin that allows you customizing high perfermance scrollbars cross browsers. It is using translate3d to perform a momentum based scrolling (aka inertial scrolling) on modern browsers. With the flexible plugin system, we can easily redesign the scrollbar as we want. This is the scrollbar plugin that you've ever dreamed of!

Installation

Via NPM (recommended):

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+

Usage

Since this package has a pkg.module field, it's highly recommended to import it as an ES6 module with some bundlers like webpack or rollup:

import Scrollbar from 'smooth-scrollbar';

Scrollbar.init(document.querySelector('#my-scrollbar'), options);

If you are not using any bundlers, you can just load the UMD bundle:

<script src="dist/smooth-scrollbar.js"></script>

<script>
  var Scrollbar = window.Scrollbar;

  Scrollbar.init(document.querySelector('#my-scrollbar'), options);
</script>

Common mistakes

Initialize a scrollbar without a limited width or height

Likes the native scrollbars, a scrollable area means the content insides it is larger than the container itself, for example, a 500*500 area with a content which size is 1000*1000:

              container
                 /
       +--------+
  #####################
  #    |        |     #
  #    |        |     #
  #    +--------+     # -- content
  #                   #
  #                   #
  #####################

Therefore, it's necessary to set the width or height for the container element:

#my-scrollbar {
  width: 500px;
  height: 500px;
  overflow: auto;
}

If the container element is natively scrollable before initializing the Scrollbar, it means you are on the correct way.

Available Options for Scrollbar

parameter	type	default	description
damping	`number`	`0.1`	Momentum reduction damping factor, a float value between `(0, 1)`, the lower the value is, the more smooth the scrolling will be (also the more paint frames).
thumbMinSize	`number`	`20`	Minimal size for scrollbar thumbs.
renderByPixels	`boolean`	`true`	Render every frame in integer pixel values, set to `true` to improve scrolling performance.
alwaysShowTracks	`boolean`	`false`	Keep scrollbar tracks always visible.
continuousScrolling	`boolean`	`true`	Set to `true` to allow outer scrollbars continue scrolling when current scrollbar reaches edge.
wheelEventTarget	`EventTarget`	`null`	Element to be used as a listener for mouse wheel scroll events. By default, the container element is used. This option will be useful for dealing with fixed elements.
plugins	`object`	`{}`	Options for plugins, see Plugin System.

Confusing with the option field? Try real-time edit tool on the bottom left!

DOM Structure

The following is the DOM structure that Scrollbar yields:

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

Documentation

latest	7.x

Demo

Okay, Let's try it:

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

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

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