jQuery custom content scroller

Custom scrollbar plugin that’s fully customizable with CSS. Features vertical/horizontal scrolling, mouse-wheel support (via jQuery mousewheel plugin), scrolling buttons, scroll inertia with easing, auto-adjustable scrollbar length, nested scrollbars, scroll-to functionality, user defined callbacks and much more.

Current version 2.8.2 (Changelog)

How to use it

Download the archive which contains all plugin files and examples. Extract and upload jquery.mCustomScrollbar.concat.min.js, jquery.mCustomScrollbar.css and mCSB_buttons.png to your web server.

Include jquery.mCustomScrollbar.css inside the head tag your html document

<link href="jquery.mCustomScrollbar.css" rel="stylesheet" type="text/css" />

Include jQuery library (if your project doesn’t use it already) and jquery.mCustomScrollbar.concat.min.js at the very bottom of your document, just before the closing body tag

<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
<script src="jquery.mCustomScrollbar.concat.min.js"></script>

After files inclusion, call mCustomScrollbar function on the element you want to add custom scrollbars. The example below adds scrollbars to elements with class name content

<script>
    (function($){
        $(window).load(function(){
            $(".content").mCustomScrollbar();
        });
    })(jQuery);
</script>

Your .content element(s) (or any other element you’re attaching the custom scrollbar) should have a typical styling of an overflowed block, e.g. a height (or max-height) value, overflow: auto (or hidden) and its content should be long enough to require a scrollbar.

To add a horizontal scrollbar, style your element accordingly (give it a width value and a wide enough content) and set the horizontalScroll option parameter of mCustomScrollbar to true

$(".content").mCustomScrollbar({
    horizontalScroll:true
});

jquery.mCustomScrollbar.css contains few ready-to-use scrollbar themes that you can apply easily on your scrollbars by setting the theme option parameter to the theme name you want

$(".content").mCustomScrollbar({
    theme:"light"
});

Detailed usage guide

jquery.mCustomScrollbar.css contains the basic styling of the custom scrollbar and should normally be included in the head tag of your html (typically before any script tags). If you wish to reduce http requests and/or have all your website stylesheet in a single file, you should move scrollbars styling in your main CSS document.

mCSB_buttons.png is a single PNG image file that contains the default, plus some additional sets for the up, down, left and right arrows used by the scrollbar buttons. I’ve created a single file in order to use CSS sprites for the button icons (defined in jquery.mCustomScrollbar.css). The plugin archive contains the PSD source (source_files/mCSB_buttons.psd) so you can add your own if you wish.

jquery.mCustomScrollbar.concat.min.js is the main plugin file which contains the custom scrollbar script as well as all necessary scripts, plugins etc. concatenated and minified. This file should be included after loading the jQuery library (the javascript library used by the plugin).

Both jQuery and plugin files can be included inside the head or body tags of your document. Including scripts at the bottom of html documents (e.g. just before the closing body tag) is usually recommended for better performance. You can load jQuery via Google’s CDN (why?) or from your own directory (the archive contains a copy of jQuery inside js folder).

The way I recommend and what I’ve used in all demos and examples is loading jQuery from a CDN (e.g. Google) and have a local copy to fallback in case CDN files won’t load

<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
<script>!window.jQuery && document.write(unescape('%3Cscript src="js/minified/jquery-1.9.1.min.js"%3E%3C/script%3E'))</script>

Call mCustomScrollbar function after jQuery and jquery.mCustomScrollbar.concat.min.js script tags. The HTML should look something like this:

<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
<script>!window.jQuery && document.write(unescape('%3Cscript src="js/minified/jquery-1.9.1.min.js"%3E%3C/script%3E'))</script>
<script src="jquery.mCustomScrollbar.concat.min.js"></script>
<script>
    (function($){
        $(window).load(function(){
            $(".content").mCustomScrollbar();
        });
    })(jQuery);
</script>

The code is wrapped in (function($){ ... })(jQuery);. This ensures no conflict between jQuery and other libraries using $ shortcut (see Using jQuery with Other Libraries for more info). The plugin function is called on window load ($(window).load()) so it executes after all page elements are fully loaded, ensuring the script calculates correctly content’s length.
If the scrollbars apply to content that has no elements with external sources (e.g. images, objects etc.) you may want to call mCustomScrollbar on document ready (so code executes when the DOM is ready)

<script>
    (function($){
        $(document).ready(function(){
            $(".content").mCustomScrollbar();
        });
    })(jQuery);
</script>

You can change the function selector (".content") to anything you want (an element id, class name, js variable etc.) – see CSS selectors. For instance, if you want custom scrollbars to apply on the element with id content-1, you simply do:

$("#content-1").mCustomScrollbar();

You may also have multiple selectors by inserting comma separated values

$(".content,#content-1").mCustomScrollbar();

The above code adds custom scrollbars to a)every element with class name content and b)the element with id content-1.
Additionally, you may want to call mCustomScrollbar multiple times within a page in order to have different options (configuration and option parameters explained below) for each selector

<script>
  (function($){
    $(window).load(function(){
      $("#content-1").mCustomScrollbar({
        horizontalScroll:true,
        autoDraggerLength:false
      });
      $("#content-2").mCustomScrollbar({
        mouseWheel:false,
        scrollButtons:{
          enable:true
        }
      });
    });
  })(jQuery);
</script>

Important notes

In order for the custom scrollbar to work correctly, your content block must be visible (i.e. should not have display:none) and its content should be fully loaded. Otherwise you must call plugin’s update method after the above conditions are met.

Hidden content blocks (either by CSS display property or jQuery $.hide()) have zero dimensions, so calling mCustomScrollbar function on them will not work. Instead, you should call the function after your elements become fully visible, so the script calculates content length correctly and apply/update the scrollbar (see live example).

If you load your content dynamically (e.g. via ajax) you must also call mCustomScrollbar function (or its update method) after content is fully loaded (e.g. on ajax success). The same applies when you programmatically change the content of elements with custom scrollbars (see ajax demo).

If for any reason you cannot insert your own code in other scripts or simply don’t know where to put it, set plugin’s updateOnContentResize option parameter to true

$(".content").mCustomScrollbar({
    advanced:{
        updateOnContentResize: true
    }
});

The above will call automatically the update method if your content’s length is changed.

Configuration

mCustomScrollbar function can get the following option parameters in order to customize scrollbar behavior and functionality

set_width: false

set_height: false

horizontalScroll: Boolean

scrollInertia: Integer

mouseWheel: Boolean

mouseWheelPixels: "auto"

autoDraggerLength: Boolean

autoHideScrollbar: Boolean

scrollButtons:{
    enable: Boolean
}

scrollButtons:{
    scrollType: String
}

scrollButtons:{
    scrollSpeed: "auto"
}

scrollButtons:{
    scrollAmount: Integer
}

advanced:{
    updateOnBrowserResize: Boolean
}

advanced:{
    updateOnContentResize: Boolean
}

advanced:{
    autoExpandHorizontalScroll: Boolean
}

advanced:{
    autoScrollOnFocus: Boolean
}

advanced:{
    normalizeMouseWheelDelta: Boolean
}

contentTouchScroll: Boolean

callbacks:{
    onScrollStart: function(){}
}

callbacks:{
  onScrollStart:function(){
    console.log("scrolling started...");
  }
}

callbacks:{
    onScroll: function(){}
}

callbacks:{
  onScroll:function(){
    console.log("content scrolled...");
  }
}

callbacks:{
    onTotalScroll: function(){}
}

callbacks:{
  onTotalScroll:function(){
    console.log("scrolled to end of content.");
  }
}

callbacks:{
    onTotalScrollBack: function(){}
}

callbacks:{
  onTotalScrollBack:function(){
    console.log("scrolled back to the beginning of content.");
  }
}

callbacks:{
    onTotalScrollOffset: Integer
}

callbacks:{
    onTotalScrollBackOffset: Integer
}

callbacks:{
    whileScrolling: function(){}
}

callbacks:{
  whileScrolling:function(){
    console.log("scrolling...");
  }
}

theme: String

Scrollbar markup

The script generates all necessary markup for the javascript scrollbar

<div class="content mCustomScrollbar _mCS_1">
  <div class="mCustomScrollBox" id="mCSB_1">
    <div class="mCSB_container">
      <!-- content -->
    </div>
    <div class="mCSB_scrollTools">
      <a class="mCSB_buttonUp"></a>
      <div class="mCSB_draggerContainer">
        <div class="mCSB_dragger">
          <div class="mCSB_dragger_bar"></div>
        </div>
        <div class="mCSB_draggerRail"></div>
      </div>
      <a class="mCSB_buttonDown"></a>
    </div>
  </div>
</div>

The original content resides inside .mCSB_container div which is also the scrollbale element. .mCSB_scrollTools contains the scrollbar and scrolling buttons. .mCSB_buttonUp and .mCSB_buttonDown are generated only in case you enable scroll buttons (see Configuration).

The markup for content blocks with horizontal scrollbars gets an additional mCSB_horizontal class and the scrolling buttons become .mCSB_buttonLeft and .mCSB_buttonRight respectively

<div class="content mCustomScrollbar _mCS_1">
  <div class="mCustomScrollBox mCSB_horizontal" id="mCSB_1">
    <div class="mCSB_container">
      <!-- content -->
    </div>
    <div class="mCSB_scrollTools">
      <a class="mCSB_buttonLeft"></a>
      <div class="mCSB_draggerContainer">
        <div class="mCSB_dragger">
          <div class="mCSB_dragger_bar"></div>
        </div>
        <div class="mCSB_draggerRail"></div>
      </div>
      <a class="mCSB_buttonRight"></a>
    </div>
  </div>
</div>

Plugin methods

update

Usage $(selector).mCustomScrollbar("update");

Calling plugin’s update method will update existing scrollbars (the script will re-calculate scrollbar length, scrolling amount etc. according to scrollable content).
You should call this method within your scripts each time you change your content dynamically (for example, when adding or removing elements with javascript, inserting new content via ajax, hiding/showing content blocks etc.).

Examples

Appending plain text content on blocks with custom scrollbars

$(".content .mCSB_container").append("<p>New content...</p>");
$(".content").mCustomScrollbar("update");

Appending an image on a block with custom scrollbars

$("#content-1 .myImagesContainer").append("<img src='myNewImage.jpg' />");
$("#content-1 .myImagesContainer img").load(function(){
  $("#content-1").mCustomScrollbar("update");
});

Animating the height of blocks with custom scrollbars

$(".content").animate({height:800},"slow",function(){
  $(this).mCustomScrollbar("update");
});

Always call the update method after newly added content is fully loaded and/or animations are completed.

scrollTo

Usage $(selector).mCustomScrollbar("scrollTo",position);

Calling plugin’s scrollTo method will automatically scroll the content to the position parameter. Scroll-to position can be a string (e.g. "#element-id", "bottom", "left" etc.) or an integer, indicating a number of pixels to scroll-to.

Examples

Scroll to the last element within your content

$(".content").mCustomScrollbar("scrollTo","last");

Scroll to element with id el-1

var elID="#el-1";
$(".content").mCustomScrollbar("scrollTo",elID);

scrollTo parameter

$(selector).mCustomScrollbar("scrollTo",String);

$(selector).mCustomScrollbar("scrollTo","top");

$(selector).mCustomScrollbar("scrollTo","bottom");

$(selector).mCustomScrollbar("scrollTo","left");

$(selector).mCustomScrollbar("scrollTo","right");

$(selector).mCustomScrollbar("scrollTo","first");

$(selector).mCustomScrollbar("scrollTo","last");

$(selector).mCustomScrollbar("scrollTo",Integer);

Method option parameters

scrollInertia: Integer

$(selector).mCustomScrollbar("scrollTo","bottom",{
  scrollInertia:3000
});

moveDragger: Boolean

$(selector).mCustomScrollbar("scrollTo",80,{
  moveDragger:true
});

callbacks: Boolean

$(selector).mCustomScrollbar("scrollTo","left",{
  callbacks:false
});

stop

Usage $(selector).mCustomScrollbar("stop");

Stops running scrolling animations. Usefull when you wish to interupt a previously scrollTo call.

disable

Usage $(selector).mCustomScrollbar("disable");

Calling mCustomScrollbar’s disable method will temporarily disable the scrollbar. Disabled scrollbars can be re-enable by calling the update method.

Method parameters

$(selector).mCustomScrollbar("disable",true);

Example of using disable method

destroy

Usage $(selector).mCustomScrollbar("destroy");

Calling destroy method will completely remove the custom scrollbar and return the element to its original state.

Example of using destroy method

Styling the scrollbars

Style your scrollbar(s) using the jquery.mCustomScrollbar.css file which contains the default scrollbar style plus a number of ready-to-use themes. You can directly change the default styling or you can keep it and add additional styles for each scrollbar (check the stylesheet inside demo_files that I’ve used to style the scrollbars for the demo and examples).

You can have separate styling for each of your scrollbars on the same page, either by giving your content blocks different class names or ids or simply by targeting them in your css like this:

._mCS_1 .mCSB_scrollTools .mCSB_dragger .mCSB_dragger_bar{
    /* 1st scrollbar dragger style... */
}
._mCS_2 .mCSB_scrollTools .mCSB_dragger .mCSB_dragger_bar{
    /* 2nd scrollbar dragger style... */
}
._mCS_3 .mCSB_scrollTools .mCSB_dragger .mCSB_dragger_bar{
    /* 3rd scrollbar dragger style... */
}

…and so on. Each content block in your document that has custom scrollbars gets automatically an additional unique class in the form of _mCS_+index number (e.g. _mCS_1) based on its index number within the DOM. Also, an additional id in the form of mCSB_+index number is generated for each .mCustomScrollBox div. This way you can easily target and style any scrollbar using its parent class name or id.

User defined callbacks

You can trigger your own js function(s) by calling them inside mCustomScrollbar callbacks option parameter

$(".content").mCustomScrollbar({
    callbacks:{
        onScroll:function(){
            myCustomFn();
        }
    }
});

function myCustomFn(){
    console.log(mcs.top);
}

In the example above, each time a scroll event ends and content has stopped scrolling, the content’s top position will be logged in browser’s console. There are available callbacks for each step of the scrolling event:

• onScrollStart – triggers the moment a scroll event starts
• whileScrolling – triggers while scroll event is running
• onScroll – triggers when a scroll event completes
• onTotalScroll – triggers when content has scrolled all the way to bottom or right
• onTotalScrollBack – triggers when content has scrolled all the way back to top or left

You can set an offset value (pixels) for both onTotalScroll and onTotalScrollBack by setting onTotalScrollOffset and onTotalScrollBackOffset respectively. For example, the following will trigger the callback function when content has scrolled to bottom minus 100 pixels

$(".content").mCustomScrollbar({
    callbacks:{
        onTotalScroll:function(){
            console.log("scrolled to bottom");
        },
    onTotalScrollOffset:100
    }
});

Returning values

The script returns a number of values and objects related to scrollbar

• this – the current element as jQuery object
• mcs.top – content’s top position (pixels)
• mcs.left – content’s left position (pixels)
• mcs.draggerTop – scrollbar dragger’s top position (pixels)
• mcs.draggerLeft – scrollbar dragger’s left position (pixels)
• mcs.topPct – content vertical scrolling percentage
• mcs.leftPct – content horizontal scrolling percentage

Example

$("#content_1").mCustomScrollbar({
    callbacks:{
        whileScrolling:function(){
            myCustomFn(this);
        }
    }
});

function myCustomFn(el){
    var msg="Content inside the element with id '"+el.attr("id")+"' has scrolled "+mcs.topPct+"%";
  console.log(msg);
}

You can see all callbacks in action on this demo

Plugin dependencies

Custom scrollbar plugin requires the following in order to work

• jQuery library
• jQuery mousewheel plugin (optional)

Mousewheel plugin (by Brandon Aaron) adds cross-browser mouse-wheel support for the scrollbar.

The production-ready plugin file – jquery.mCustomScrollbar.concat.min.js contains the plugin script and mousewheel plugin, concatenated and minified.
jquery.mCustomScrollbar.js contains the plugin script (uncompressed) and loads dependencies (all except jQuery) via CDN.
All script files and dependencies are available separately (uncompressed and minified version included) inside js directory.

Loading scripts separately

If you prefer to load the plugin script and each dependency separately (example included in the archive), you can do the following

<!-- Google CDN jQuery with fallback to local -->
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
<script>!window.jQuery && document.write(unescape('%3Cscript src="js/minified/jquery-1.9.1.min.js"%3E%3C/script%3E'))</script>
<!-- CloudFlare CDN mousewheel plugin with fallback to local -->
<script src="//cdnjs.cloudflare.com/ajax/libs/jquery-mousewheel/3.0.6/jquery.mousewheel.min.js"></script>
<script>$.event.special.mousewheel || document.write('<script src="js/minified/jquery.mousewheel.min.js"><\/script>')</script>
<!-- custom scrollbars plugin -->
<script src="js/minified/jquery.mCustomScrollbar.min.js"></script>

Each script loads via CDN and falls-back to local files in case CDN fails.

License

You are free to use, study, improve and modify this script wherever and however you like.
All works are licensed under GNU General Public License, GNU Lesser General Public License or Creative Commons Attribution 3.0 Unported License.

Donating helps greatly in developing and updating free software and running this blog :)