Highly Customizable Custom Overlay Scrollbar Plugin With jQuery

Highly Customizable Custom Overlay Scrollbar Plugin With jQuery
File Size: 143 KB
Views Total:
Last Update:
Publish Date:
Official Website: Go to website
License: MIT
   

The jQuery OverlayScrollbars plugin provides a simple way to create customizable, themeable overlay scrollbars on any scrollable element while preserving the native scroll functionality.

Features:

  • Touch-enabled.
  • RTL supported.
  • CSS3 animated.
  • Cross browser.
  • High performance.

Basic usage:

1. Include the main stylesheet and a theme CSS of your choice on the head section of the webpage.

<!-- 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">

2. Include both jQuery JavaScript library and the jquery.overlayScrollbars.js script on the page.

<script src="https://code.jquery.com/jquery-1.12.4.min.js" integrity="sha384-nvAa0+6Qg9clwYCGGPpDQLVpLNn0fRaROjHqs13t4Ggj3Ez50XnGQqc/r8MhnRDZ" crossorigin="anonymous"></script>
<script src="js/jquery.overlayScrollbars.js"></script>

3. Call the function on the target scrollable element and specify the theme Class you want to use. 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
$('body').overlayScrollbars({
  className: "os-theme-dark"
}); 

4. More configuration options to customize the scrollbars.

$('body').overlayScrollbars({

  // 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
  },

  // Defines special behavior of textarea elements.
  textarea : {
    dynWidth : false,  //true || false
    dynHeight : false  //true || false
  }
  
}); 

5. Callback functions.

$('body').overlayScrollbars({

  callbacks : {
    onInitialized : null,               //null || function
    onInitializationWithdrawn : null,   //null || function
    onDestroyed : null,                 //null || function
    onScrollStart : null,               //null || function
    onScroll : null,                    //null || function
    onScrollStop: null,                 //null || function
    onOverflowChanged : null,           //null || function
    onOverflowAmountChanged : null,     //null || function
    onDirectionChanged : null,          //null || function
    onContentSizeChanged : null,        //null || function
    onHostSizeChanged : null,           //null || function
    onUpdated : null                    //null || function
  }
  
}); 

6. API methods.

var instance = $('body').overlayScrollbars({    
    // options here
}); 

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

// updates scrollbars
instance.update([force])

// puts the instance to sleep
instance.sleep()

// returns the current scroll information.
instance.scroll()

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

// stops the current scroll-animation.
instance.scrollStop()

// returns all relevant elements.
instance.getElements()

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

// removes scrollbars from DOM
instance.destroy()

Change log:

2018-05-19

  • v1.4.5

This awesome jQuery plugin is developed by KingSora. For more Advanced Usages, please check the demo page or visit the official website.