jQuery Custom Scrollbar

jQuery Custom Scrollbar is a jQuery plugin that lets you add fully customizable scrollbars to your sites. With the plugin you can apply any css styles you want to your scrollbars.

Features

• vertical and horizontal scrollbars you can style your own way
• scrolling by mouse dragging, mouse wheel, keyboard – just as you would with native browser scrollbar
• touch scrolling on mobile devices (Android, iPhone and iPad)
• a couple predefined skins showing you how to style scrollbars
• simple api that lets you scroll programmatically and be notified about scroll events

Requirements

The plugin supports all major browsers: Chrome, Firefox, IE 7+.

To use the plugin you obviously need jQuery (it should work in jQuery 1.4 and later versions).

Download

You can download the latest version here

Demos

In demos folder of this repo, there are some example usages of custom scrollbar and its api. The demos are also available online here

Usage

First download and add jquery.custom-scrollbar.js and jquery.custom-scrollbar.css to your site.

Suppose you have a container on your site with some lengthy content and you want to make it scrollable:

<div class="container">
  <!-- Some lengthy content -->
</div>

Define it’s width and height (below some example size is used):

.container {
  width: 300px;
  height: 400px;
}

Add a skin class to your container:

<div class="container default-skin">
  <!-- Some lengthy content -->
</div>

In the example we use default-skin. Plugin comes with two other predefined skins: gray-skin and modern-skin. You are not limited to that and you can style scrollbar your own way.

Finally call this js code:

$(document).ready(function() {
  $(".container").customScrollbar();
});

If container content does not fit in those sizes scrollbar will appear.

The above method will add vertical scrollbar only. If you also want to add horizontal scrollbar, there is one more css step required:

.container .overview {
  width: 1000px;
}

This defines example total width of the scrolled content (not just the width of the visible part as in previous step).

Options

There are some options you can pass when initializing scrollbar:

Option	Type	Default value	Description
animationSpeed	Integer	300	Speed of the animation of programatic scrolling.
hScroll	Boolean	true	Indicates whether or not, horizontal scrollbar should be shown when it’s necessary.
skin	String	undefined	A css skin class that will be added to the scrolled container. You can define it in html as well as here in options. Note that skin has to be defined in one of those ways.
updateOnWindowResize	Boolean	false	Indicates whether scrollbar should recalculate thumb size when window is resized. See demos/resize.html for an example.
vScroll	Boolean	true	Same as above but applies to vertical scrollbar.

For example:

$("#my-container").customScrollbar({
  skin: "default-skin", 
  hScroll: false,
  updateOnWindowResize: true
  })

API

There are some methods of the plugin you may want to call.

scrollTo(element)

Scrolls viewport to a given element inside scrolled content. An element might be jQuery object or a selector string. To controll animation speed use animationSpeed initialization option. Example usage:

$(".container").customScrollbar("scrollTo", "#some-element-inside-container")

scrollToX(x)

Sets horizontal scrollbar position to x pixels. x should be in range from 0 to scrolled content width. If it’s outside that range, content will be scrolled to the start or to the end. To controll animation speed use animationSpeed initialization option.

$(".container").customScrollbar("scrollToX", 100)

scrollToY(y)

Sets vertical scrollbar position to y pixels. x should be in range from 0 to scrolled content height. If it’s outside that range, content will be scrolled to the start or to the end. To controll animation speed use animationSpeed initialization option.

$(".container").customScrollbar("scrollToY", 200)

resize()

Recalculates and sets sizes of all scrollbar components. Call this whenever your scrolled block changes its size and
scrollbar becomes invalid. After you call it scrollbar is adjusted to new sizes of your block.

$(".container").customScrollbar("resize")

remove()

Removes all the DOM changes and event bindings added by the plugin.

$(".container").customScrollbar("remove")

Events

customScroll

Triggered whenever content is scrolled. Separate events are fired when vertical and horizontal scrollbar is moved.

$(".container").on("customScroll", function(event, scrollData) {});

Handler function takes two arguments. event is standard jquery event object. scrollData is an object with 3 fields holding scroll specific information:

• scrollPercent – integer in range 0..100 indicating percentage position of the scrollbar
• scrollDirection – string that can take following 4 values: left, right, up, down – indicates what direction the scrollbar was moved in
• scrollAxis – string indicating which scrollbar was moved: X for horizontal scrollbar and Y for vertical scrollbar

You can also bind handler to that event when initializing scrollbar:

$(".container").customScrollbar({
  onCustomScroll: function(event, scrollData) {}
});