Performant Custom Scrollbar JavaScript Library – SimpleBar

Category: Javascript , Recommended | January 16, 2022
Views Total:10,360 views
Official Page:Go to website
Last Update:January 16, 2022


Performant Custom Scrollbar JavaScript Library – SimpleBar


SimpleBar is a simple, standalone JavaScript library that appends a custom scrollbar to any scrollable container which has overflowing content. Works with CSS overflow: auto property and keeps the native scroll behavior.

How to use it:

Install the SimpleBar and import it into your web project.

$ npm install simplebar --save
// ES 6
import SimpleBar from 'simpleBar';

Or directly include the SimpleBar’s JavaScript and CSS files on the html page.

<link href="dist/simplebar.css" rel="stylesheet">
<script src="dist/simplebar.js"></script>

Add the ‘data-simplebar’ attribute to your scrollable container and done.

<div data-simplebar id="demo">
  content here
.demo {
  height: 300px;
  width: 400px;
  overflow: hidden;

To initialize the Simplebar manually:

new SimpleBar(document.getElementById('demo'))

To config the Simplebar, override the options as shown below and pass the object as the second parameter to the ‘Simplebar’ function.

new SimpleBar(document.getElementById('demo'), {
    autoHide: true,
    forceVisible: false,
    classNames: {
      resizeWrapper: 'simplebar-resize-wrapper',
      content: 'simplebar-content',
      offset: 'simplebar-offset',
      mask: 'simplebar-mask',
      wrapper: 'simplebar-wrapper',
      placeholder: 'simplebar-placeholder',
      scrollbar: 'simplebar-scrollbar',
      track: 'simplebar-track',
      heightAutoObserverWrapperEl: 'simplebar-height-auto-observer-wrapper',
      heightAutoObserverEl: 'simplebar-height-auto-observer',
      visible: 'simplebar-visible',
      horizontal: 'simplebar-horizontal',
      vertical: 'simplebar-vertical',
      hover: 'simplebar-hover',
      dragging: 'simplebar-dragging'
    scrollbarMinSize: 25,
    scrollbarMaxSize: 0,
    direction: 'ltr',
    timeout: 1000

API methods.

myInstance = new SimpleBar(document.getElementById('demo'), {
  // options here
// recalculates the height/width of content
// gets scroll element
// gets content element
// removes observer


v6.0.0 (01/16/2023)

  • SimpleBar v6 does not use any polyfill anymore by default
  • timeout option is now deprecated. It is now only made with a CSS transition that you can override with CSS as you want
  • mutation-observer polyfill is not shipped by default anymore
  • core-js is not included anymore. We now use TypeScript instead of Babel so polyfilling is up to you
  • Bundle is much smaller
  • New useful classes on host element
  • Scrollbar recalculations are now throttled with RAQ instead of Lodash’s throttle function, which prevents stuttering on animation

v5.3.8 (05/24/2019)

  • Fix a case where flexbox display could not work properly

v5.0.6 (11/07/2019)

  • Fix a case where flexbox display could not work properly

v5.0.2 (10/19/2019)

  • Fix a case where flexbox display could not work properly

v4.1.0 (07/03/2019)

  • Fix a case where flexbox display could not work properly
  • Fix scrollbar width detection calculation being wrong in some zoom levels

v4.0 (05/21/2019)

  • Add “dragging” class when scrollbar is dragged
  • Avoid unnecessary array copies for NodeList iteration
  • Bugfixes


  • fix: remove missing DOM listeners on unmount


  • fix: fix vue plugin tests not passing


  • fix: capture pointer events instead of bubbling


  • Fix ‘visible’ classname bug when using custom classnames


  • fix wrong scrollbar position calculation when track has padding


  • Add ‘visible’, ‘horizontal’ and ‘vertical’ classnames to options


  • Fix handle not being draggable on IE/Edge


  • Fix horizontal scrollbar missing same logic as vertical one


  • Force the scrollbar to be displayed when hovered;

v3.0.0beta (07/15/2018)

  • Update

You Might Be Interested In:

Leave a Reply