smooth-scrollbar

In 8.x, options.syncCallbacks has been removed because scrolling listeners are always invoked synchronously. To perform asynchronous actions within a listener, wrap your logic in requestAnimationFrame.

// equivalent in 8.x
scrollbar.addListener(() => {
  requestAnimationFrame(() => {
    // do something
  });
});

You can install smooth-scrollbar using NPM (recommended) or Bower to add it to your project dependencies.

npm install smooth-scrollbar --save

Plugins are invoked in the order they are registered via Scrollbar.use() (First-In-First-Out).

If you have multiple plugins that modify the delta, the output of the first plugin becomes the input for the second. Be mindful of this order, especially when using plugins that modify layout (like OverscrollPlugin), which should typically be registered last.

// PluginA's transformDelta runs, then PluginB's transformDelta runs
Scrollbar.use(PluginA, PluginB);

In version 8.x, the overscroll effect is no longer bundled with the main package. You must import and use the OverscrollPlugin manually.

import OverscrollPlugin from 'smooth-scrollbar/plugins/overscroll';

Scrollbar.use(OverscrollPlugin);

Scrollbar.init(elem, {
  plugins: {
    overscroll: options | false,
  },
});

The Overscroll plugin provides macOS-style bouncing effects or Android-style glow effects during overscrolling.

To use it with a module bundler:

1. Import OverscrollPlugin from smooth-scrollbar/plugins/overscroll.
2. Register it using Scrollbar.use(OverscrollPlugin).
3. Enable it in the Scrollbar.init configuration under plugins.overscroll.

To use it via <script> tags:

1. Include dist/smooth-scrollbar.js and dist/plugins/overscroll.js.
2. Register it using Scrollbar.use(window.OverscrollPlugin).
3. Enable it in the Scrollbar.init configuration.

import OverscrollPlugin from 'smooth-scrollbar/plugins/overscroll';

Scrollbar.use(OverscrollPlugin);

Scrollbar.init(elem, {
  plugins: {
    overscroll: {
      effect: 'bounce'
    },
  },
});

If you are using a bundler like Webpack or Rollup, import Scrollbar as an ES6 module and call Scrollbar.init() passing the DOM element you want to use as the scroll container.

import Scrollbar from 'smooth-scrollbar';

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

You can install smooth-scrollbar using NPM (recommended) or Bower.

npm install smooth-scrollbar --save

To use smooth-scrollbar, initialize it on a container element using Scrollbar.init().

Important: The container element must have a defined width or height and be natively scrollable (e.g., overflow: auto) before initialization. This ensures the content inside is larger than the container itself.

Using ES6 Modules (Recommended)

Use this method with bundlers like Webpack or Rollup:

import Scrollbar from 'smooth-scrollbar';

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

Using UMD Bundle

If you are not using a bundler, load the script via a <script> tag:

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

<script>
  var Scrollbar = window.Scrollbar;

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

If you are not using a bundler, load the UMD bundle via a <script> tag. The Scrollbar instance will be available on the global window object.

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

<script>
  var Scrollbar = window.Scrollbar;

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

When upgrading from version 7.x to 8.x, note the following major changes:

• CSS: smooth-scrollbar.css has been removed. You only need to import the main JS module/bundle.
• Plugin System: Many features previously included in the core (like overscroll and speed control) have been moved to a plugin-based architecture.
• Options & Methods: Several core options and methods have been removed or changed in signature to favor the plugin system or more explicit configuration objects.

To prevent the overscroll plugin from being constructed on a specific scrollbar, set plugins.overscroll to false during initialization.

Scrollbar.init(elem, {
  plugins: {
    overscroll: false,
  },
});