This website uses cookies to personalise ads and to analyse traffic ok
web design

jQuery custom content scroller

jQuery custom content scroller

Highly customizable custom scrollbar jQuery plugin. Features include vertical and/or horizontal scrollbar(s), adjustable scrolling momentum, mouse-wheel (via jQuery mousewheel plugin), keyboard and touch support, ready-to-use themes and customization via CSS, RTL direction support, option parameters for full control of scrollbar functionality, methods for triggering actions like scroll-to, update, destroy etc., user-defined callbacks and more.

Current version 3.1.5 (Changelog)
Upgrading from version 2

When upgrading from version 2.x to 3.x it’s important to use version 3 CSS and .png files. Version 3 is backwards compatible but it’s also a huge overhaul. One significant change is that you don’t need to call the update method manually (the script does it automatically). For more info see changelog.

Version 2 is still maintained and updated here.


How to use it

Get started by downloading the archive which contains the plugin files (and a large amount of HTML demos and examples). Extract and upload jquery.mCustomScrollbar.concat.min.js, jquery.mCustomScrollbar.css and mCSB_buttons.png to your web server (alternatively you can load plugin files from a CDN).

Instead of hosting the plugin files on your web server, you can load them directly from a CDN like jsdelivr, Github etc.

  • jsdelivr versioned/minified
    • //cdn.jsdelivr.net/jquery.mcustomscrollbar/3.0.6/jquery.mCustomScrollbar.concat.min.js
    • //cdn.jsdelivr.net/jquery.mcustomscrollbar/3.0.6/jquery.mCustomScrollbar.min.css
    • //cdn.jsdelivr.net/jquery.mcustomscrollbar/3.0.6/mCSB_buttons.png
  • Github latest/minified
    • //malihu.github.io/custom-scrollbar/jquery.mCustomScrollbar.concat.min.js
    • //malihu.github.io/custom-scrollbar/jquery.mCustomScrollbar.min.css
    • //malihu.github.io/custom-scrollbar/mCSB_buttons.png


HTML

Include jquery.mCustomScrollbar.css in the head tag your HTML document (more info)

jquery.mCustomScrollbar.css contains the styling of the custom scrollbar and themes. It 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/copy scrollbars styling in your main CSS document.

mCSB_buttons.png contains all the button arrows (up, down, left and right) as image sprites for all scrollbar themes. The plugin archive contains the PSD source (source-files/mCSB_buttons.psd) so you can change them or add your own. This file should be in the same directory with plugin stylesheet.


<link rel="stylesheet" href="/path/to/jquery.mCustomScrollbar.css" />

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

Some frameworks and CMS include jQuery library in the head tag to make sure it’s loaded when other scripts request it. Usually, including .js files on the bottom of the HTML document (just before the closing body tag) is recommended for better performance. In any case, jQuery must be included first, before plugin scripts.


<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
<script src="/path/to/jquery.mCustomScrollbar.concat.min.js"></script>

CSS

The element(s) you want to add scrollbar(s) should have the typical CSS properties of an overflowed block which are a height (or max-height) value, an overflow value of auto (or hidden) and content long enough to require scrolling. For horizontal scrollbar, the element should have a width (or max-width) value set.

If you prefer to set your element’s height/width via javascript, you can use the setHeight/setWidth option parameters.

Initialization

Initialize via javascript

After files inclusion, call mCustomScrollbar function on the element selector you want to add the scrollbar(s)

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

more info

The code is wrapped in (function($){ ... })(jQuery);. This ensures no conflict between jQuery and other libraries using $ shortcut (see Avoiding Conflicts with Other Libraries for more info). The plugin function is called in $(window).on("load") so it executes after all page elements (like images) are loaded.

You can change the function selector ".content" to any selector you want (an element id, class name, js variable etc.). 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 set different options (configuration and option parameters explained below) for each selector

<script>
  (function($){
    $(window).on("load",function(){
      $("#vertical-content").mCustomScrollbar({
        theme:"light-3",
        scrollButtons:{
          enable:true
        }
      });
      $("#horizontal-content").mCustomScrollbar({
        axis:"x",
        theme:"3d"
      });
    });
  })(jQuery);
</script>

Initialize via HTML

Add the class mCustomScrollbar to any element you want to add custom scrollbar(s) with default options. Optionally, set its axis via the HTML data attribute data-mcs-axis (e.g. "x" for horizontal and "y" for vertical) and its theme via data-mcs-theme. For example:

<div class="mCustomScrollbar" data-mcs-theme="dark">
  <!-- your content -->
</div>

Basic configuration & option parameters

axis

By default, the script applies a vertical scrollbar. To add a horizontal or 2-axis scrollbars, invoke mCustomScrollbar function with the axis option set to "x" or "yx" respectively

$(".content").mCustomScrollbar({
    axis:"x" // horizontal scrollbar
});
$(".content").mCustomScrollbar({
    axis:"yx" // vertical and horizontal scrollbar
});

theme

To quickly change the appearance of the scrollbar, set the theme option parameter to any of the ready-to-use themes available in jquery.mCustomScrollbar.css, for example:

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

Configuration

You can configure your scrollbar(s) using the following option parameters on mCustomScrollbar function
Usage $(selector).mCustomScrollbar({ option: value });

setWidth: false
Set the width of your content (overwrites CSS width), value in pixels (integer) or percentage (string).
setHeight: false
Set the height of your content (overwrites CSS height), value in pixels (integer) or percentage (string).
setTop: 0
Set the initial css top property of content, accepts string values (css top position).
Example: setTop: "-100px".
setLeft: 0
Set the initial css left property of content, accepts string values (css left position).
Example: setLeft: "-100px".
axis: "string"
Define content’s scrolling axis (the type of scrollbars added to the element: vertical and/of horizontal).
Available values: "y", "x", "yx".

  • axis: "y" – vertical scrollbar (default)
  • axis: "x" – horizontal scrollbar
  • axis: "yx" – vertical and horizontal scrollbars
scrollbarPosition: "string"
Set the position of scrollbar in relation to content.
Available values: "inside", "outside".
Setting scrollbarPosition: "inside" (default) makes scrollbar appear inside the element. Setting scrollbarPosition: "outside" makes scrollbar appear outside the element. Note that setting the value to "outside" requires your element (or parent elements) to have CSS position: relative (otherwise the scrollbar will be positioned in relation to document’s root element).
scrollInertia: integer
Set the amount of scrolling momentum as animation duration in milliseconds.
Higher value equals greater scrolling momentum which translates to smoother/more progressive animation. Set to 0 to disable.
autoDraggerLength: boolean
Enable or disable auto-adjusting scrollbar dragger length in relation to scrolling amount (same bahavior with browser’s native scrollbar).
Set autoDraggerLength: false when you want your scrollbar to (always) have a fixed size.
autoHideScrollbar: boolean
Enable or disable auto-hiding the scrollbar when inactive.
Setting autoHideScrollbar: true will hide the scrollbar(s) when scrolling is idle and/or cursor is out of the scrolling area.
Please note that some special themes like “minimal” overwrite this option.
autoExpandScrollbar: boolean
Enable or disable auto-expanding the scrollbar when cursor is over or dragging the scrollbar.
alwaysShowScrollbar: integer
Always keep scrollbar(s) visible, even when there’s nothing to scroll.

  • alwaysShowScrollbar: 0 – disable (default)
  • alwaysShowScrollbar: 1 – keep dragger rail visible
  • alwaysShowScrollbar: 2 – keep all scrollbar components (dragger, rail, buttons etc.) visible
snapAmount: integer
Make scrolling snap to a multiple of a fixed number of pixels. Useful in cases like scrolling tabular data, image thumbnails or slides and you need to prevent scrolling from stopping half-way your elements. Note that your elements must be of equal width or height in order for this to work properly.
To set different values for vertical and horizontal scrolling, use an array: [y,x]
snapOffset: integer
Set an offset (in pixels) for the snapAmount option. Useful when for example you need to offset the snap amount of table rows by the table header.
mouseWheel:{ enable: boolean }
Enable or disable content scrolling via mouse-wheel.
mouseWheel:{ scrollAmount: integer }
Set the mouse-wheel scrolling amount (in pixels). The default value "auto" adjusts scrolling amount according to scrollable content length.
mouseWheel:{ axis: "string" }
Define the mouse-wheel scrolling axis when both vertical and horizontal scrollbars are present.
Set axis: "y" (default) for vertical or axis: "x" for horizontal scrolling.
mouseWheel:{ preventDefault: boolean }
Prevent the default behaviour which automatically scrolls the parent element when end or beginning of scrolling is reached (same bahavior with browser’s native scrollbar).
mouseWheel:{ deltaFactor: integer }
Set the number of pixels one wheel notch scrolls. The default value “auto” uses the OS/browser value.
mouseWheel:{ normalizeDelta: boolean }
Enable or disable mouse-wheel (delta) acceleration. Setting normalizeDelta: true translates mouse-wheel delta value to -1 or 1.
mouseWheel:{ invert: boolean }
Invert mouse-wheel scrolling direction. Set to true to scroll down or right when mouse-wheel is turned upwards.
mouseWheel:{ disableOver: [array] }
Set the tags that disable mouse-wheel when cursor is over them.
Default value:
["select","option","keygen","datalist","textarea"]
scrollButtons:{ enable: boolean }
Enable or disable scrollbar buttons.
scrollButtons:{ scrollAmount: integer }
Set the buttons scrolling amount (in pixels). The default value "auto" adjusts scrolling amount according to scrollable content length.
scrollButtons:{ scrollType: "string" }
Define the buttons scrolling type/behavior.

  • scrollType: "stepless" – continuously scroll content while pressing the button (default)
  • scrollType: "stepped" – each button click scrolls content by a certain amount (defined in scrollAmount option above)
scrollButtons:{ tabindex: integer }
Set a tabindex value for the buttons.
keyboard:{ enable: boolean }
Enable or disable content scrolling via the keyboard.
The plugin supports the directional arrows (top, left, right and down), page-up (PgUp), page-down (PgDn), Home and End keys.
keyboard:{ scrollAmount: integer }
Set the keyboard arrows scrolling amount (in pixels). The default value "auto" adjusts scrolling amount according to scrollable content length.
keyboard:{ scrollType: "string" }
Define the keyboard arrows scrolling type/behavior.

  • scrollType: "stepless" – continuously scroll content while pressing the arrow key (default)
  • scrollType: "stepped" – each key release scrolls content by a certain amount (defined in scrollAmount option above)
contentTouchScroll: integer
Enable or disable content touch-swipe scrolling for touch-enabled devices.
To completely disable, set contentTouchScroll: false.
Integer values define the axis-specific minimum amount required for scrolling momentum (default: 25).
documentTouchScroll: boolean
Enable or disable document touch-swipe scrolling for touch-enabled devices.
advanced:{ autoExpandHorizontalScroll: boolean }
Auto-expand content horizontally (for "x" or "yx" axis).
If set to true, content will expand horizontally to accommodate any floated/inline-block elements.
Setting its value to 2 (integer) forces the non scrollHeight/scrollWidth method. A value of 3 forces the scrollHeight/scrollWidth method.
advanced:{ autoScrollOnFocus: "string" }
Set the list of elements/selectors that will auto-scroll content to their position when focused.
For example, when pressing TAB key to focus input fields, if the field is out of the viewable area the content will scroll to its top/left position (same bahavior with browser’s native scrollbar).
To completely disable this functionality, set autoScrollOnFocus: false.
Default:
"input,textarea,select,button,datalist,keygen,a[tabindex],area,object,[contenteditable='true']"
advanced:{ updateOnContentResize: boolean }
Update scrollbar(s) automatically on content, element or viewport resize.
The value should be true (default) for fluid layouts/elements, adding/removing content dynamically, hiding/showing elements etc.
advanced:{ updateOnImageLoad: boolean }
Update scrollbar(s) automatically each time an image inside the element is fully loaded.
Default value is auto which triggers the function only on "x" and "yx" axis (if needed).
The value should be true when your content contains images and you need the function to trigger on any axis.
advanced:{ updateOnSelectorChange: "string" }
Update scrollbar(s) automatically when the amount and size of specific selectors changes.
Useful when you need to update the scrollbar(s) automatically, each time a type of element is added, removed or changes its size.
For example, setting updateOnSelectorChange: "ul li" will update scrollbars each time list-items inside the element are changed.
Setting the value to true, will update scrollbars each time any element is changed.
To disable (default) set to false.
advanced:{ extraDraggableSelectors: "string" }
Add extra selector(s) that’ll release scrollbar dragging upon mouseup, pointerup, touchend etc.
Example: extraDraggableSelectors: ".myClass, #myID"
advanced:{ releaseDraggableSelectors: "string" }
Add extra selector(s) that’ll allow scrollbar dragging upon mousemove/up, pointermove/up, touchend etc.
Example: releaseDraggableSelectors: ".myClass, #myID"
advanced:{ autoUpdateTimeout: integer }
Set the auto-update timeout in milliseconds.
Default timeout: 60
theme: "string"
Set the scrollbar theme.
View all ready-to-use themes
All themes are contained in plugin’s CSS file (jquery.mCustomScrollbar.css).
Default theme: "light"
callbacks:{
      onCreate: function(){}
}
A function to call when plugin markup is created.
Example:
callbacks:{
    onCreate:function(){
      console.log("Plugin markup generated");
    }
}
callbacks:{
      onInit: function(){}
}
A function to call when scrollbars have initialized (demo).
Example:
callbacks:{
    onInit:function(){
      console.log("Scrollbars initialized");
    }
}
callbacks:{
      onScrollStart: function(){}
}
A function to call when scrolling starts (demo).
Example:
callbacks:{
    onScrollStart:function(){
      console.log("Scrolling started...");
    }
}
callbacks:{
      onScroll: function(){}
}
A function to call when scrolling is completed (demo).
Example:
callbacks:{
    onScroll:function(){
      console.log("Content scrolled...");
    }
}
callbacks:{
      whileScrolling: function(){}
}
A function to call while scrolling is active (demo).
Example:
callbacks:{
    whileScrolling:function(){
      console.log("Scrolling...");
    }
}
callbacks:{
      onTotalScroll: function(){}
}
A function to call when scrolling is completed and content is scrolled all the way to the end (bottom/right) (demo).
Example:
callbacks:{
    onTotalScroll:function(){
      console.log("Scrolled to end of content.");
    }
}
callbacks:{
      onTotalScrollBack: function(){}
}
A function to call when scrolling is completed and content is scrolled back to the beginning (top/left) (demo).
Example:
callbacks:{
    onTotalScrollBack:function(){
      console.log("Scrolled back to the beginning of content.");
    }
}
callbacks:{
      onTotalScrollOffset: integer
}
Set an offset for the onTotalScroll option.
For example, setting onTotalScrollOffset: 100 will trigger the onTotalScroll callback 100 pixels before the end of scrolling is reached.
callbacks:{
      onTotalScrollBackOffset: integer
}
Set an offset for the onTotalScrollBack option.
For example, setting onTotalScrollBackOffset: 100 will trigger the onTotalScrollBack callback 100 pixels before the beginning of scrolling is reached.
callbacks:{
      alwaysTriggerOffsets: boolean
}
Set the behavior of calling onTotalScroll and onTotalScrollBack offsets.
By default, callback offsets will trigger repeatedly while content is scrolling within the offsets.
Set alwaysTriggerOffsets: false when you need to trigger onTotalScroll and onTotalScrollBack callbacks once, each time scroll end or beginning is reached.
callbacks:{
      onOverflowY: function(){}
}
A function to call when content becomes long enough and vertical scrollbar is added.
Example:
callbacks:{
    onOverflowY:function(){
      console.log("Vertical scrolling required");
    }
}
callbacks:{
      onOverflowX: function(){}
}
A function to call when content becomes wide enough and horizontal scrollbar is added.
Example:
callbacks:{
    onOverflowX:function(){
      console.log("Horizontal scrolling required");
    }
}
callbacks:{
      onOverflowYNone: function(){}
}
A function to call when content becomes short enough and vertical scrollbar is removed.
Example:
callbacks:{
    onOverflowYNone:function(){
      console.log("Vertical scrolling is not required");
    }
}
callbacks:{
      onOverflowXNone: function(){}
}
A function to call when content becomes narrow enough and horizontal scrollbar is removed.
Example:
callbacks:{
    onOverflowXNone:function(){
      console.log("Horizontal scrolling is not required");
    }
}
callbacks:{
      onBeforeUpdate: function(){}
}
A function to call right before scrollbar(s) are updated.
Example:
callbacks:{
    onBeforeUpdate:function(){
      console.log("Scrollbars will update");
    }
}
callbacks:{
      onUpdate: function(){}
}
A function to call when scrollbar(s) are updated.
Example:
callbacks:{
    onUpdate:function(){
      console.log("Scrollbars updated");
    }
}
callbacks:{
      onImageLoad: function(){}
}
A function to call each time an image inside the element is fully loaded and scrollbar(s) are updated.
Example:
callbacks:{
    onImageLoad:function(){
      console.log("Image loaded");
    }
}
callbacks:{
      onSelectorChange: function(){}
}
A function to call each time a type of element is added, removed or changes its size and scrollbar(s) are updated.
Example:
callbacks:{
    onSelectorChange:function(){
      console.log("Scrollbars updated");
    }
}
live: "string"
Enable or disable applying scrollbar(s) on all elements matching the current selector, now and in the future.
Set live: true when you need to add scrollbar(s) on elements that do not yet exist in the page. These could be elements added by other scripts or plugins after some action by the user takes place (e.g. lightbox markup may not exist untill the user clicks a link).
If you need at any time to disable or enable the live option, set live: "off" and "on" respectively.
You can also tell the script to disable live option after the first invocation by setting live: "once".
liveSelector: "string"
Set the matching set of elements (instead of the current selector) to add scrollbar(s), now and in the future.

Plugin methods

Ways to execute various plugin actions programmatically from within your script(s).

update

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

Call the update method to manually update existing scrollbars to accommodate new content or resized element(s). This method is by default called automatically by the script (via updateOnContentResize option) when the element itself, its content or scrollbar size changes.

view examples

/* initialize plugin with auto-update options disabled */
$(selector).mCustomScrollbar({
  advanced:{
    updateOnContentResize: false,
    updateOnImageLoad: false
  }
});

/* at some point in your js script/code update scrollbar manually */
$(selector).mCustomScrollbar("update");

scrollTo

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

Call the scrollTo method to programmatically scroll the content to the position parameter (demo).

position parameter

Position parameter can be:

  • "string"
    • e.g. element selector: "#element-id"
    • e.g. special pre-defined position: "bottom"
    • e.g. number of pixels less/more: "-=100"/"+=100"
  • integer
    • e.g. number of pixels: 100
  • [array]
    • e.g. different y/x position: [100,50]
  • object/function
    • e.g. jQuery object: $("#element-id")
    • e.g. js object: document.getelementbyid("element-id")
    • e.g. function: function(){ return 100; }

Pre-defined position strings:

  • "bottom" – scroll to bottom
  • "top" – scroll to top
  • "right" – scroll to right
  • "left" – scroll to left
  • "first" – scroll to the position of the first element within content
  • "last" – scroll to the position of the last element within content

view examples

Scroll to element with id “#el-1″

$(selector).mCustomScrollbar("scrollTo","#el-1");

Scroll to top

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

Scroll by 100 pixels down or right

var val=100;
$(selector).mCustomScrollbar("scrollTo","-="+val);

Scroll by 100 pixels up or left

$(selector).mCustomScrollbar("scrollTo","+=100");

Scroll by 100 pixels down and by 50 pixels right

$(selector).mCustomScrollbar("scrollTo",["-=100","-=50"]);

Scroll to the fifth paragraph

$(selector).mCustomScrollbar("scrollTo",$("p:eq(4)"));

Scroll to the last element within your content

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

Scroll to some variable value

var val=document.getelementbyid("element-id");
$(selector).mCustomScrollbar("scrollTo",val);

Scroll to 300 pixels

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

Method options

scrollInertia: integer
Scroll-to duration, value in milliseconds.
Example:
$(selector).mCustomScrollbar("scrollTo","bottom",{
    scrollInertia:3000
});
scrollEasing: "string"
Scroll-to animation easing, values: "linear", "easeOut", "easeInOut".
Example:
$(selector).mCustomScrollbar("scrollTo","bottom",{
    scrollEasing:"easeOut"
});
moveDragger: boolean
Scroll scrollbar dragger (instead of content).
Example:
$(selector).mCustomScrollbar("scrollTo",80,{
    moveDragger:true
});
timeout: integer
Set a timeout for the method (the default timeout is 60 ms in order to work with automatic scrollbar update), value in milliseconds.
Example:
$(selector).mCustomScrollbar("scrollTo","top",{
    timeout:1000
});
callbacks: boolean
Trigger user defined callbacks after scroll-to completes.
Example:
$(selector).mCustomScrollbar("scrollTo","left",{
    callbacks:false
});

stop

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

Stops any running scrolling animations (usefull when you wish to interupt a previously scrollTo method call).

disable

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

Calling disable method will temporarily disable the scrollbar (demo). Disabled scrollbars can be re-enable by calling the update method.

To disable the scrollbar and reset its content position, set the method’s reset parameter to true

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

view examples

/* initialize plugin */
$(selector).mCustomScrollbar();

/* at some point in your js script/code disable scrollbar */
$(selector).mCustomScrollbar("disable");

/* re-enable scrollbar as needed */
$(selector).mCustomScrollbar("update");

destroy

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

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

view examples

/* initialize plugin */
$(selector).mCustomScrollbar();

/* at some point in your js script/code destroy scrollbar */
$(selector).mCustomScrollbar("destroy");

Scrollbar styling & themes

You can design and visually customize your scrollbars with pure CSS, using jquery.mCustomScrollbar.css which contains the default/basic styling and all scrollbar themes.

The easiest/quickest way is to select a ready-to-use scrollbar theme. For example:

$(selector).mCustomScrollbar({
  theme:"dark"
});

View all ready-to-use themes

You can modify the default styling or any theme either directly in jquery.mCustomScrollbar.css or by overwriting the CSS rules in another stylesheet.

Creating a new scrollbar theme

Create a name for your theme (e.g. “my-theme”) and set it as the value of the theme option

$(selector).mCustomScrollbar({
    theme:"my-theme"
});

Your element will get the class “mCS-my-theme” (your theme-name with “mCS” prefix), so you can create your CSS using the .mCS-my-theme in your rules. For instance:

.mCS-my-theme.mCSB_scrollTools .mCSB_dragger .mCSB_dragger_bar{ background-color: red; }
.mCS-my-theme.mCSB_scrollTools .mCSB_draggerRail{ background-color: white; } 
/* and so on... */

In the same manner you can clone any existing theme (e.g. “dark”), change its selector (e.g. .mCS-dark) to your own theme name (e.g. .mCS-my-theme) and modify its CSS rules.

Scrollbar markup

The plugin applies specific id (unique) and/or classes to every scrollbar element/component, meaning that you can target and modify any scrollbar in more than one ways.

For example, every element with a scrollbar gets a unique class in the form of _mCS_1, _mCS_2 etc. Every scrollbar container element gets a unique id in the form of mCSB_1_scrollbar_vertical, mCSB_2_scrollbar_vertical etc. Every scrollbar dragger gets a unique id in the form of mCSB_1_dragger_vertical, mCSB_2_dragger_vertical etc. in addition to the class mCSB_dragger. All these mean that you can do stuff like:

._mCS_1 .mCSB_dragger .mCSB_dragger_bar{ background-color: red; }

._mCS_2 .mCSB_dragger .mCSB_dragger_bar{ background-color: green; }

#mCSB_3_dragger_vertical .mCSB_dragger_bar{ background-color: blue; }

#mCSB_1_scrollbar_vertical .mCSB_dragger{ height: 100px; }

#mCSB_1_scrollbar_horizontal .mCSB_dragger{ width: 100px; }

.mCSB_1_scrollbar .mCSB_dragger .mCSB_draggerRail{ width: 4px; }

Custom scrollbar layout

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(this);
        }
    }
});

function myCustomFn(el){
    console.log(el.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 (view 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
    }
});

By default, onTotalScroll and onTotalScrollBack callbacks are triggered repeatedly. To prevent multiple calls when content is within their offset, set alwaysTriggerOffsets option to false (view example).

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

Additional callbacks:

Returning values

The script returns a number of values and objects related to scrollbar that you can use in your own functions

  • this – the original element containing the scrollbar(s)
  • this.mcs.content – the original content wrapper as jquery object
  • this.mcs.top – content’s top position (pixels)
  • this.mcs.left – content’s left position (pixels)
  • this.mcs.draggerTop – scrollbar dragger’s top position (pixels)
  • this.mcs.draggerLeft – scrollbar dragger’s left position (pixels)
  • this.mcs.topPct – content vertical scrolling percentage
  • this.mcs.leftPct – content horizontal scrolling percentage
  • this.mcs.direction – content’s scrolling direction (y or x)

view examples

Load more content when scrolled to bottom

$(selector).mCustomScrollbar({
    callbacks:{
        onTotalScroll:function(){
            this.mcs.content.append("...");
        }
    }
});

Run code when at least half of the content is scrolled

$(selector).mCustomScrollbar({
    callbacks:{
        whileScrolling:function(){
            var pct=this.mcs.topPct;
            if(pct>=50){
              /* do something... */
            }
        }
    }
});

Plugin-specific jQuery expressions

$("#myID:mcsInView")
Select element(s) in your content that are within scrollable viewport.
As condition: $("#myID").is(":mcsInView");
$(".content:mcsOverflow")
Select overflowed element(s) with visible scrollbar.
As condition: $(".content").is(":mcsOverflow");
$("#myID:mcsInSight")
$("#myID:mcsInSight(exact)")
Select element(s) in your content that are in view of the scrollable viewport. Using the exact parameter will include elements that have any part of them (even 1 pixel) in view of the scrollable viewport.
As condition: $("#myID").is(":mcsInSight");, $("#myID").is(":mcsInSight(exact)");

Plugin dependencies & requirements

License

This work is released under the MIT License.
You are free to use, study, improve and modify it wherever and however you like.
https://opensource.org/licenses/MIT

Pages: 1 2 3 4


5,618 Comments

Post a comment

Comments pages: 1 2 3 84

  1. Surdo
    Posted on December 31, 2010 at 02:04 Permalink

    Really great lessons on your site:) Thanks a lot mate.

    Surdo

    Reply
  2. Madeline
    Posted on December 30, 2010 at 23:01 Permalink

    Nice jquery content sliders. Its nice that you can style it to match the color theme. Will be using these.

    Reply
  3. Sachin
    Posted on December 30, 2010 at 07:10 Permalink

    Excellent jquery for website. thanks for code support.

    Reply
  4. Zach Leatherman
    Posted on December 29, 2010 at 15:41 Permalink

    Looks great. I think it could be a little better if the click target for hitting a specific point on the scrollbar (anywhere not on the drag anchor) was wider than 1px. Seems awfully hard to hit.

    Reply
    • malihu
      Posted on December 29, 2010 at 19:09 Permalink

      Hi Zach,
      Yes 1-2px is indeed hard to hit… With some padding or transparent images as background it’s easily fixed. Thanks for your comment πŸ™‚

      Reply
  5. Ashish
    Posted on December 28, 2010 at 07:01 Permalink

    OMG..!!

    This is the thing I was waiting for…!!
    That’s really amazing… Thank you very much for this.

    Just one thing, All the JS required for this became very heavy in size(293 kbs) including the CSS.

    I there any way to make this less in size…

    Please reply.

    Again thank you very much for this…….!!

    Reply
    • malihu
      Posted on December 28, 2010 at 15:12 Permalink

      Hello Ashish,

      Thank you for your comments πŸ™‚

      The plugin (jquery.mCustomScrollbar.js) is about 8kb in size (un-minified). The rest of the files (except jquery itself) needed to implement it are:

      The CSS (jquery.mCustomScrollbar.css). The one I created for the demo is little over 7kb and consists 5 scrollbars.

      The jquery.easing.1.3.js, which is also 7kb.

      And the jquery.mousewheel.min.js (about 1kb).

      That’s an additional 23-25kb plus the jquery itself (which is better loaded from Google, so it’s always cached). Everything else depends on the markup and images (if any).

      Reply
    • kevin
      Posted on March 3, 2011 at 23:26 Permalink

      True but not true if you search a bit. On the Jquery Ui’s site you can create a custom version of the file with only what you need.

      I just needed the minimum for the scroll in itself which is: Core, Widget, Mouse and Draggable. This gave me a 28kb file.

      I even went further with a javascript compression algorithm and got a 26kb file.

      Reply
  6. michaelpaguay
    Posted on December 27, 2010 at 19:52 Permalink

    would this also work to change the browser’s scrollbar?
    like in this website.

    Reply
    • malihu
      Posted on December 27, 2010 at 20:54 Permalink

      Not really. It could only work if you place your entire content inside div.content and set the body, mcs_container etc. display to “fixed” and width to “100%” in your stylesheet.

      Reply
      • michaelpaguay
        Posted on December 30, 2010 at 03:55 Permalink

        figured :/
        any idea how this was made?
        i tried looking at the source but found nothing.
        and tried google, that’s how i came across this.

        thanks

        Reply
  7. Toz
    Posted on December 23, 2010 at 14:06 Permalink

    Love it.

    But could you please help? I don’t know where to start if I wanna modify this to horizontal bar.

    Reply
    • malihu
      Posted on December 23, 2010 at 14:50 Permalink

      Hi,
      I’m currently creating a plugin out of this script, so if you can wait a couple of days, you’ll be able to implement vertical as well as horizontal scrollbars easily πŸ˜‰

      Edit: done

      Reply
      • Toz
        Posted on December 24, 2010 at 04:40 Permalink

        That is awesome!

        Reply
    • malihu
      Posted on December 25, 2010 at 04:36 Permalink

      Hello again Toz,
      Just finished the plugin. Please re-download the files and check the post for information on how to implement the plugin.

      Reply
      • Toz
        Posted on December 25, 2010 at 08:21 Permalink

        This is truly awesome. Thank you very much for letting me know.
        πŸ˜‰

        Reply
      • Fred
        Posted on May 23, 2011 at 21:44 Permalink

        I’m using the vertical scroll bar with the buttons.
        I love it but I’m trying to set a fixed scroll movement for the buttons.
        Lets say that I want to scroll with each click, 50px down. Can this be done? How?
        Thank you!

        Reply
  8. Markos
    Posted on December 10, 2010 at 12:48 Permalink

    Hey, thanks! Really helpful!
    Used it at: http://www.mariatheodoradimaki.com

    Reply
    • malihu
      Posted on December 12, 2010 at 15:48 Permalink

      super πŸ™‚

      Reply
  9. jesper MΓΈller
    Posted on December 7, 2010 at 13:55 Permalink

    IS it posible to use the Script externaly, insted fo placing the script at the bottom of the page?
    is yes. How ?

    Reply
    • malihu
      Posted on December 12, 2010 at 15:46 Permalink

      Yes of course. Make a new .js file and copy the script content inside it. Give it a filename (e.g. jquery.customscrollbar.js) and then load it in your document (before the closing body tag) like any other javascript files.

      Reply
  10. Don Carswell
    Posted on November 23, 2010 at 16:24 Permalink

    oops,
    I meant 3.6, does not matter too much anyway if there is not fix for it

    Reply
  11. Don Carswell
    Posted on November 16, 2010 at 16:37 Permalink

    Its a cool scroll bar.
    I am having a little trouble with it displaying on firefox.
    IE, Chrome is fine.
    FF 2.6 has a huge gap down below.
    Check out http://www.khaosok-accommodation.com/activities.html for an example.

    How can I fix this?

    It seems to put the height of the whole text on .container, I have tried adding height to it which fixes the height problem but then the scroll bar goes missing.

    Thanks

    Reply
    • malihu
      Posted on November 18, 2010 at 10:21 Permalink

      Hello Don,

      I normally do not check the scripts on old browsers (such as firefox 2, ie6 etc.) as they have varius implementation bugs and issues with css and javascript.

      Reply
  12. isHristov
    Posted on November 15, 2010 at 23:50 Permalink

    You are welcome! πŸ™‚
    I can show you the project where I implemented this one (and one more of your scripts) in a few weeks if you are interested.

    Reply
    • malihu
      Posted on November 16, 2010 at 01:16 Permalink

      Of course I am πŸ™‚

      Reply
  13. isHristov
    Posted on November 12, 2010 at 12:52 Permalink

    Okay, you can see the code here. It’s in txt file. πŸ™‚

    Reply
    • isHristov
      Posted on November 12, 2010 at 21:01 Permalink

      You can update my first post from today and delete the other crap (including this one). πŸ™‚

      Reply
      • malihu
        Posted on November 14, 2010 at 19:22 Permalink

        Thanks a lot! Will do πŸ™‚

        Edit: Done! Code, post, demo and download files are updated. Thanks a lot for your input isHristov.

        Reply
  14. isHristov
    Posted on November 12, 2010 at 12:46 Permalink

    Ooops, that’s bad. The code that must be added didn’t pass the validation.
    New try. The code should be:

    (remove hyphen) #customScrollBox { overflow:auto; } #dragger_container { display:none; } (remove hyphen)

    Reply
  15. isHristov
    Posted on November 12, 2010 at 12:42 Permalink

    Hello again. πŸ™‚
    I wasn’t very happy (at all) with my previous solution to the javascript-disabled problem so I come up with a new one. The problem with the previous fix was that in case javascript is enabled then for a few ms you would see the ugly default scroller and then the new scroller would be loaded. We definitely don’t want that.

    The new solution basically is to return to your original code (display the nice scroller by default) and add just a tiny fix ONLY in case javascript is disabled with noscript tag. Step by step:

    Change: "#customScrollBox{position:relative; height:600px; overflow:auto;}" to "#customScrollBox{position:relative; height:600px; overflow:hidden;}" //return to your original code Remove "display: none;" from #dragger_container{position:relative; width:0px; height:580px; float:left; margin:10px 0 0 10px; border-left:1px solid #000; border-right:1px solid #555; "display: none;} //same here Remove the following lines from the JS code: $customScrollBox.css("overflow", "hidden"); $dragger_container.css("display", "block"); //same here So now we have your original code before my fist suggestion. The only thing we must add is: #customScrollBox { overflow:auto; } #dragger_container { display:none; } //this should go right after your markup (after you close all those divs for the scroller). This code adds the two properties to #customScrollBox and #dragger_container to display the standart and ugly scroller in case of disabled javascript

    I think this solution is better. πŸ™‚

    Reply
  16. darkcus
    Posted on November 4, 2010 at 19:04 Permalink

    I love It!!!! too cool!!!! thks

    Reply
  17. Rali Madhu
    Posted on October 30, 2010 at 15:19 Permalink

    I am looking for same like scroller, unfortunately i found this one.
    Thanks Dear.

    Reply
    • dumper
      Posted on December 29, 2010 at 22:14 Permalink

      uh.. what?

      Reply
  18. nyanshiki
    Posted on October 22, 2010 at 16:25 Permalink

    Excellent, but how to fix bug when using customized colors and clicking dragger, it changes back to default colors?

    Reply
    • malihu
      Posted on October 22, 2010 at 16:40 Permalink

      Find functions DraggerOver() and DraggerOut() inside script and change their color values for foreground, background, borders etc.

      Reply
  19. Paul
    Posted on October 22, 2010 at 11:55 Permalink

    Perfect! Thanks a lot!!!

    Reply
  20. isHristov
    Posted on October 22, 2010 at 00:45 Permalink

    Hi, man! Your work is pretty amazing and I trully appreciate it!
    I was thinking in implementing this script in one of my projects so I wanted to see if it’s okay with you.

    However, while testing, I saw that the scrollbox dies in case Javascript is disabled so I’ve made a few changes to make it degrade in case of this scenario.
    You can update yours if you like. πŸ™‚

    The CSS:
    Change: "#customScrollBox{position:relative; height:600px; overflow:hidden;}" to "#customScrollBox{position:relative; height:600px; overflow:auto;}" //tp make sure the default look will be with scroll if necessary Add "display: none;" to #dragger_container{position:relative; width:0px; height:580px; float:left; margin:10px 0 0 10px; border-left:1px solid #000; border-right:1px solid #555;} //to make sure the dragger_container is not shown by default. <b>The JS code:</b> After if($customScrollBox_container.height()>visibleHeight){ (line 11), add the following: $customScrollBox.css("overflow", "hidden"); $dragger_container.css("display", "block"); //in case Javascript is enabled this script is executed, default scrollbar is hidden and custom dragger_container is displayed.

    P.S. Your blog is awesome! I lost electricity while writing this and when I came back later the comment I was writing was still here! Genius! LocalStorage I guess?

    Reply
    • malihu
      Posted on October 22, 2010 at 01:55 Permalink

      Amazing mate, thanks a lot πŸ™‚
      I’ll update the post as soon as possible!

      Edit: done.

      Reply
    • Dave
      Posted on June 30, 2011 at 04:23 Permalink

      I’ve just started using this plugin (it’s awesome!) however, I’m finding that sometimes it doesn’t scroll to the bottom of the content. It may scroll 80% down then the scroller reaches the end, however the bottom of the content is not visible.

      Any ideas what could possibly be causing this? Thank you!

      Reply
  21. Manos
    Posted on October 7, 2010 at 16:40 Permalink

    Man, your ideas come from a different dimension… Great post, well done!

    Reply
  22. Dave
    Posted on September 20, 2010 at 13:31 Permalink

    Hi,
    This is a neat demo, however it’s basically unusable on my Mac thanks to the inertial scrolling already built into OS X. Scrolling using either the built-in trackpad or the Magic mouse causes the content to scroll instantly to the top or bottom at the slightest touch. πŸ™

    Reply
    • malihu
      Posted on September 20, 2010 at 13:41 Permalink

      Thanks for the input Dave
      Unfortunately I didn’t checked this script on a mac. I’ll check it and see if there’s anything I can do to fix it.

      Reply
    • dumper
      Posted on December 29, 2010 at 22:11 Permalink

      i can diagnose your problem. its that your using a mac…

      Reply
      • no
        Posted on February 1, 2012 at 12:35 Permalink

        HAH HAH HAH HAH GOOD ONE

        hang yourself.

        Reply
    • malihu
      Posted on February 16, 2011 at 14:33 Permalink

      Hello again!
      Inside jquery.mCustomScrollbar.js find the line var vel = Math.abs(delta*10); and change 10 to a lower number (e.g. 1).
      That should help.

      Reply
  23. Vadim
    Posted on September 14, 2010 at 13:37 Permalink

    Looks very nice indeed! Any plans to make a plugin out of this code? Also the scrollTo method would be really useful, as well as horizontal scroller, min bar height etc. (take look at jScrollPane). In fact I believe that with this component as a plugin you and your site could become famous :-). Please do not forget the license, because people get confused as you can see in the above comments… PS: all your other examples are great too!

    Reply
    • malihu
      Posted on September 15, 2010 at 01:01 Permalink

      Hi Vadim, thanks for your comments πŸ™‚

      Unfortunately I don’t have much time to make a plugin at the moment but I hope I’ll find some time in the future. I was thinking about horizontal scrolling too so I might give a go πŸ˜‰ The reason for not using scrollTo is because I wanted to use some easing with the scrolling, so I went with animate. I also feel a bit more familiar with animate cause I develop a lot with actionscript.

      Reply
      • Vadim
        Posted on September 15, 2010 at 04:04 Permalink

        What I meant by scrollTo was the ability to scroll to a certain selector (inside the container) with some method provided by your potential plugin. So animate() can be used for it too…

        Reply
      • malihu
        Posted on September 16, 2010 at 01:55 Permalink

        I see. I might give it a go if I make a plugin out of it. Thanks for the suggestion πŸ™‚

        Reply
        • Bigorangemachine
          Posted on September 7, 2012 at 18:32 Permalink

          I like scrollTo.
          With scrollTo you can still scroll to an int as well as a specific DOM Object

          Reply
  24. Puntidivista
    Posted on September 10, 2010 at 09:57 Permalink

    Thank you so much for this component, i really enjoy it!
    i’m searching this days for something like that, and i have found just it here πŸ˜‰

    Just one question: the mouse scrolling doesn’t work, is there some problems with css absolute position, or other css trouble that make it unwork?

    thank you again

    Reply
    • malihu
      Posted on September 11, 2010 at 03:29 Permalink

      Hello,
      It should work fine with position:absolute tho I’d have to see the actual code to see if there are any problems.

      Reply
  25. Rocky
    Posted on September 6, 2010 at 09:34 Permalink

    Really nice and very useful content. Great work buddy, keep it up

    Reply
  26. Michael
    Posted on September 3, 2010 at 00:09 Permalink

    Cool, just started a new project today and this little beauty here will come in very very handy πŸ™‚

    You will get a link from me soon !

    Reply
  27. allyreid
    Posted on August 17, 2010 at 11:14 Permalink

    Been looking for something like this for ages, amazing.

    Reply
  28. e11world
    Posted on August 6, 2010 at 21:18 Permalink

    LOOOOOVE the easing animation on the mouse wheel. Very very useful!!

    Reply
  29. Studentenjob
    Posted on August 2, 2010 at 23:01 Permalink

    This is very nice, I think I will use it on a commercial project if I am allowed to πŸ™‚

    Reply
    • admin
      Posted on August 3, 2010 at 00:10 Permalink

      You are allowed to use it anywhere/anyhow you like. If you eventually use it on a project of yours it would be cool to let me know πŸ™‚ cheers

      Reply
      • reese
        Posted on January 12, 2011 at 22:10 Permalink

        Hi, nice plugin. But is it possible to use a div with a scrollbar (let’s say horizontal) inside a div with a vertical scrollbar?
        I don’t mean two scrollbars for the same content, but for two different contents.
        Something like this http://img692.imageshack.us/img692/7899/screenshot001mh.png

        Thanks

        Reply
      • malihu
        Posted on January 13, 2011 at 01:59 Permalink

        @reese

        It’s not possible as it is (out-of-the-box). It should be possible but honestly I can’t tell how much work it needs to be done in order to do it. Unfortunately, at the moment I work on so many things, I can’t tell when I’ll be able to try it.

        Reply
      • Sim Hua Soon
        Posted on May 17, 2011 at 12:59 Permalink

        Hi,

        It’s a great plugin. I have adapted it into a Confluence extension. Check it out at Akeles Space Lister Extension.

        Thank you

        Reply
      • Ward van den Berg
        Posted on January 28, 2012 at 20:50 Permalink

        Hi there,

        Very good plugin! Compliments!
        If you don’t object, I’d like to use it in my new site.

        One question though…
        I use a later jquery version and it appears that the scroll only works in Firefox…
        In all other browsers, the scrollbar moves alright, but the content doesn’t…
        When I use your link to the Google api jquery 1.4.4 it works fine.

        Any idea why this is?
        Thanks!

        Ward

        Reply
      • Lucas Schlottfeldt
        Posted on April 1, 2012 at 23:49 Permalink

        Hey, great job!!! I’m using thin on a new project. After I done with the job I’ll show you the result and give the apropriated credit for you and your website in the html and css code line.

        Reply
      • Sachyn
        Posted on April 3, 2012 at 10:24 Permalink

        Loved it. Was wondering if I can use it in an iframe ?

        Reply
      • chris peck
        Posted on April 22, 2012 at 19:35 Permalink

        i followed all the directions, scroll bar looks good, but wont scroll. I am using inside an iframe on Facebook.

        Your long content goes here…
        Your long content goes here…
        Your long content goes here…
        Your long content goes here…
        Your long content goes here…
        Your long content goes here…
        Your long content goes here…
        Your long content goes here…
        Your long content goes here…
        Your long content goes here…
        Your long content goes here…
        Your long content goes here…
        Your long content goes here…
        Your long content goes here…
        Your long content goes here…
        Your long content goes here…
        Your long content goes here…
        Your long content goes here…
        Your long content goes here…
        Your long content goes here…
        Your long content goes here…
        Your long content goes here…
        Your long content goes here…
        Your long content goes here…
        Your long content goes here…
        Your long content goes here…
        Your long content goes here…
        Your long content goes here…
        Your long content goes here…
        Your long content goes here…
        Your long content goes here…
        Your long content goes here…
        Your long content goes here…
        Your long content goes here…
        Your long content goes here…
        Your long content goes here…
        Your long content goes here…
        Your long content goes here…
        Your long content goes here…
        testing
        testing
        testing
        testing
        testing
        testing
        testing
        testing
        testing

        $(window).load(function() {
        $(“#mcs2_container”).mCustomScrollbar(“vertical”,400,”easeOutCirc”,1.05,”auto”,”yes”,”yes”,10);
        });

        <script src="we2tng/js/scroll/jquery.mCustomScrollbar.js” type=”text/javascript”>

        Reply
      • Brent C
        Posted on May 15, 2012 at 03:49 Permalink

        Great script! I used it on Nutffles.com

        Reply
    • Amanda
      Posted on April 11, 2012 at 22:14 Permalink

      Hi, I loved your plugin, but I found a small problem. It does not work on iphone/ipad! πŸ™ Is there any solution?

      thanks and congrats for the wonderful work!

      Reply
    • Anand Prakash
      Posted on April 25, 2012 at 14:03 Permalink

      I am trying to use this plugin inside a CMS (http://get-simple.info) to scroll the content dynamically inserted by the CMS. The plugin fails. The entire content moves together out of the view and goes in the opposite direction. If I remove the dynamic content code and insert normal text, the plugin behaves correctly, meaning that my files, paths and everything else is put together correctly.

      How do I make it work with this CMS?

      Reply

Comments pages: 1 2 3 84

Post a comment

Cancel reply

Your e-mail is never published nor shared. Required fields are marked *

You may use these HTML tags and attributes:
<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>
You can write or copy/paste code directly in your comment using the <code> tag:
<code>code here...</code>
You may also use the data-lang attribute to determine the code language like so:
<code data-lang-html>, <code data-lang-css>, <code data-lang-js> and <code data-lang-php>

css.php