Performant Custom Scrollbar JavaScript Library – SimpleBar

Preview:

Description:

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
$ 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
</div>

.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
myInstance.recalculate();
// gets scroll element
myInstance.getScrollElement();
// gets content element
myInstance.getContentElement();
// removes observer
myInstance.removeObserver();

Changelog:

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

01/17/2019

• fix: remove missing DOM listeners on unmount

01/14/2019

• fix: fix vue plugin tests not passing

11/19/2018

• fix: capture pointer events instead of bubbling

11/14/2018

• Fix ‘visible’ classname bug when using custom classnames

11/02/2018

• fix wrong scrollbar position calculation when track has padding

10/16/2018

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

08/19/2018

• Fix handle not being draggable on IE/Edge

08/10/2018

• Fix horizontal scrollbar missing same logic as vertical one

08/01/2018

• Force the scrollbar to be displayed when hovered;

v3.0.0beta (07/15/2018)

• Update