Elegant Themeable Custom Scrollbars – OverlayScrollbars

Category: Javascript , Recommended | October 11, 2019
Author: KingSora
Views Total: 2,464
Official Page: Go to website
Last Update: October 11, 2019
License: MIT


Elegant Themeable Custom Scrollbars – OverlayScrollbars


OverlayScrollbars is a JavaScript library used to create elegant, customizable and themeable scrollbars on any scrollable elements. Available in Vanilla JavaScript and also can be used as a jQuery plugin.

How to use it:

Install the OverlayScrollbars via NPM.

$ npm install overlayscrollbars --save

Import the OverlayScrollbars module.

// ES 6
import OverlayScrollbars from 'overlayscrollbars';

// CommonJS:
const OverlayScrollbars = require('overlayscrollbars');

Import the core stylesheet and a theme CSS into the page.

<!-- Main -->
<link href="css/OverlayScrollbars.css" rel="stylesheet">

<!-- round dark -->
<link href="css/os-theme-round-dark.css" rel="stylesheet">

<!-- round light -->
<link href="css/os-theme-round-light.css" rel="stylesheet">

<!-- block dark -->
<link href="css/os-theme-block-dark.css" rel="stylesheet">

<!-- block light -->
<link href="css/os-theme-block-light.css" rel="stylesheet">

<!-- minimal dark -->
<link href="css/os-theme-minimal-dark.css" rel="stylesheet">

<!-- minimal light -->
<link href="css/os-theme-minimal-light.css" rel="stylesheet">

<!-- thick dark -->
<link href="css/os-theme-thick-dark.css" rel="stylesheet">

<!-- thick light -->
<link href="css/os-theme-thick-light.css" rel="stylesheet">

<!-- thin dark -->
<link href="css/os-theme-thin-dark.css" rel="stylesheet">

<!-- thin light -->
<link href="css/os-theme-thin-light.css" rel="stylesheet">

Apply the custom scrollbars to the scrollable containers. Available themes:

  • os-theme-dark: built-in
  • os-theme-light: built-in
  • os-theme-minimal-dark
  • os-theme-minimal-light
  • os-theme-thin-dark
  • os-theme-thin-light
  • os-theme-thick-dark
  • os-theme-thick-light
  • os-theme-round-dark
  • os-theme-round-light
  • os-theme-block-dark
  • os-theme-block-light
var instance = OverlayScrollbars(document.getElementsByTagName('body'), {
    className       : "os-theme-dark" 

var instance2 = OverlayScrollbars(document.getElementById('demo'), {
   className       : "os-theme-round-dark",
   resize          : "both",
    sizeAutoCapable : true,
    paddingAbsolute : true 

More customization options.


  // none || both  || horizontal || vertical || n || b || h || v
  resize : 'none',                

  // true || false
  sizeAutoCapable : true,         

  // true || false
  clipAlways : true,              

  // true || false
  normalizeRTL : true,            

  // true || false
  paddingAbsolute : false,        

  // true || false || null
  autoUpdate : null,              

  // number
  autoUpdateInterval : 33,      

  // These options are only respected if the native scrollbars are overlaid.  
  nativeScrollbarsOverlaid : {
    showNativeScrollbars : false,   //true || false
    initialize : true               //true || false

  // Defines how the overflow should be handled for each axis
  overflowBehavior : {

    // visible-hidden  || visible-scroll || hidden || scroll || v-h || v-s || h || s
    x : 'scroll', 

    // visible-hidden  || visible-scroll || hidden || scroll || v-h || v-s || h || s
    y : 'scroll'  

  // Defines the behavior of the custom scrollbars.
  scrollbars : {
    visibility : 'auto',    //visible || hidden || auto || v || h || a
    autoHide : 'never',     //never || scroll || leave || n || s || l
    autoHideDelay : 800,    //number
    dragScrolling : true,   //true || false
    clickScrolling : false, //true || false
    touchSupport : true     //true || false
    snapHandle: true     //true || false

  // Defines special behavior of textarea elements.
  textarea : {
    dynWidth : false,  //true || false
    dynHeight : false  //true || false
    inheritedAttrs : inheritedAttrsTemplate //string || array || null

Callback functions.

callbacks: {
  onInitialized: callbackTemplate,                                 
  onInitializationWithdrawn: callbackTemplate,                     
  onDestroyed: callbackTemplate,                                   
  onScrollStart: callbackTemplate,                                 
  onScroll: callbackTemplate,                                      
  onScrollStop: callbackTemplate,                                  
  onOverflowChanged: callbackTemplate,                             
  onOverflowAmountChanged: callbackTemplate,                       
  onDirectionChanged: callbackTemplate,                            
  onContentSizeChanged: callbackTemplate,                          
  onHostSizeChanged: callbackTemplate,                             
  onUpdated: callbackTemplate                                      

API methods.

// adds new options
instance.options(optionName, optionValue)

// updates scrollbars

// puts the instance to sleep

// returns the current scroll information.

// sets the scroll position.
instance.scroll(coordinates [, duration] [, easing] [, complete])

// stops the current scroll-animation.

// returns all relevant elements.

// returns a object which describes the current state of this instance.

// removes scrollbars from DOM

// checks whether a passed object is a non-destroyed OverlayScrollbars instance


v1.10.0 (10/11/2019)

  • The host element of a textarea element now applies the focus class if the textarea get focused.
  • Improved event handling & management (passive & preventDefault e.g. non-passive events)
  • The plugin now recognizes already existing DOM (helpful in component wrappers & PHP / SSR Sites)

v1.9.1 (08/03/2019)

  • Fixed a bug where the plugin didn’t update correctly if you changed interleaved options twice in a row to the same value

v1.9.0 (07/27/2019)

  • Fixed a bug where unexpected scroll jumps happened after you changed a option.
  • Fixed a bug where a min-width change wasn’t detected if width is auto
  • Fixed a bug where the update function didn’t update a textarea properly, when only its value changed and due to that its size.
  • A new global method OverlayScrollbars.valid which checks whether a passed object is a non-destroyed OverlayScrollbars instance.

v1.8.0 (07/09/2019)

  • Bugs fixed.
  • The getState() methods returned object contains now a new property called destroyed which indicates that the instance has been destroyed.
  • Changed the management of passive event listeners: touch events which call prefentDefault() are now added with passive : false, all other events which should be passive and don’t call prefentDefault() are added with passive : true.
  • Preparation for framework wrappers such as react, vue and angular: the option() method will now only cause a call to the update() method if at least one option has been truly changed.
  • Cleaner handling of the internal update() method.

v1.7.3 (06/24/2019)

  • Fixed – the status of the DOM / MutationObservers is now synchronized if you call the scroll or update function.
  • Fixed – the used MutationObserver listens now to the open attribute.
  • Fixed a bug where you can’t resize the host element when its size was 0 previously.
  • Fixed an IE8 bug where the plugin didn’t work correctly.

v1.7.2 (06/11/2019)

  • Fixed a bug where width: auto elements had incorrect width if paddingAbsolute was true.
  • OverlayScrollbars has better perfomance on Firefox now because it utilizes the new scrollbar-width CSS Property.
  • Improved perfomance on all browsers which are using natively overlaid scrollbars (mobile, OS-X etc.).
  • Changes to the textarea size measuring process, which results also in better performance if plugin is initialized on textarea elements.

v1.7.1 (05/23/2019)

  • Fixed instance.scroll({ y: “100%” }) probelm

v1.7.0 (04/18/2019)

  • A new option scrollbars.snapHandle was added which helps you to control how the scrollbar-handle behaves if you use CSS Snap Scrolling.
  • The scroll() methods returned object now has a new property called snappedHandleOffset.
  • CSS Snap Scrolling has now deeper support: The handle dragging is now smooth (controlled with the new option scrollbars.snapHandle) and the jump-back if you let go midway has now a transition.
  • If you set a handle-max-size and the overflow is way to small, the resulting jump-back if you let go midway has now a transition.
  • If you drag the handle the next calculated scroll-position is now rounded instead of floored which results in better user-experience.
  • Click scrolling is now more precise.
  • Bugs fixed.


  • v1.6.3


  • v1.6.1


  • v1.5.3


  • Remove the use of depcreated .hover() method


  • v1.5.2

You Might Be Interested In:

Leave a Reply