Elegant Themeable Custom Scrollbars – OverlayScrollbars

Category: Javascript , Recommended | July 20, 2022
Views Total:291 views
Official Page:Go to website
Last Update:July 20, 2022


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,
  // control on which elements / selectors OverlayScrollbars shall update automatically after the emit of a load event
  updateOnLoad: ['img'],
  // 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.13.3 (07/20/2022)

  • change appear animation detection from z-index to cursor.
  • only call image callback when the plugin isn’t destroyed.

v1.13.2 (06/01/2022)

  • Update

v1.13.1 (12/16/2020)

  • Fixed z-index of .os-padding
  • Fixed passive event-listeners on touch events

v1.13.0 (08/03/2020)

  • If you drag the scrollbar handle the click event won’t be propagated to the body to be closer to the native behavior.
  • The .os-padding element has now default z-index.
  • Clickscrolling amount & speed adjusts now to the scrollbar-handle size to be more accurate.
  • The RTL(right to left) style won’t be applied to the body element anymore to be closer to the native behavior.

v1.12.0 (04/06/2020)

  • ‘max-content’ is now used to detect the possible size if width is not fixed. (only if supported by the browser else the old algo. is used)
  • Updated all wrapper versions to better support frontend frameworks.
  • Removed useless touchevents from the host element
  • A new option called ‘updateOnLoad’ with which you can control on which elements / selectors OverlayScrollbars shall update automatically after the emit of a load event. Per default the value is set to [“img”] so the plugin will updated after any img emits a load event. You can set it to null to disable this auto updating entierly or add your own selectors to update only on special img elements or on for example loaded iframes.
  • Bugfixes

v1.11.0 (03/01/2020)

  • Changed RTL behavior detection to support the Chromium web interoperability effort
  • Implemented a way to intuitively set the tabindex attribute of the viewport element
  • Changed restrictedMeasuring workaround (works via CSS now).
  • Removed unnecessary CSS
  • If ResizeObserver is supported, it now detects changes in padding in Chrome again.

v1.10.3 (02/03/2020)

  • The cache of the scroll infos which can be get by the scroll method is now updated immediately after you use the scroll method to change the position.
  • Fixed: Reference Error: previousOverflow is not defined

v1.10.2 (12/31/2019)

  • Fixed a bug where the overflow wasn’t calculated properly on the newest firefox in some cases.
  • Fixed a bug where the usage of a MutationObserver in connection with zone.js freezed the browser.

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