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="http://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.
http://opensource.org/licenses/MIT

Pages: 1 2 3 4


5,581 Comments

Post a comment

Comments pages: 1 8 9 10 11 12 83

  1. tom
    Posted on January 19, 2012 at 11:50 Permalink

    Hi,
    I have noticed weird behavior of scrollbar in Chrome (version 16.0.912.75) under Ubuntu 10.04 and win7. I use your scrollbar in hide/show divs so I call mCustomScrollbar() after hidden div is shown. And what it does? Dragger is moving fine but content not. And I found the code with comment “function to fix the -10000 pixel limit of jquery.animate”, so I deleted it and voala problem in Chrome was solved. Without this “fix” I haven’t noticed any weird behavior. So maybe someone can use this help or find a better solution.

    Reply
    • malihu
      Posted on January 19, 2012 at 21:07 Permalink

      Hey, thanks for posting this 🙂 Maybe the newer version of jquery doesn’t need this “hack” to animate 9999 pixels blocks.

      Reply
      • tom
        Posted on March 20, 2012 at 11:54 Permalink

        Yeah maybe. I was using jQuery v1.7.1

        Reply
      • Christian
        Posted on May 18, 2012 at 13:47 Permalink

        Sorry for my bad english.
        I had the same problem. After removing the -10.000 bug fix everything works fine!

        Can anyone find out if they’ve removed the -10.000 bug in the current version of jquery?

        Reply
      • Donovan
        Posted on June 7, 2012 at 23:44 Permalink

        I think this might be the problem I am having. I posted a new comment at the bottom of the page with links to the issue.

        Where in the code can I find the “function to fix the -10000 pixel limit of jquery.animate” so I can delete it to see if it fixes the issue for me.

        Reply
  2. Chris
    Posted on January 19, 2012 at 04:47 Permalink

    Hi,

    I have a problem whereby I am embedding youtube / vimeo clips (iframes) within the scroller, which works fine, except that when the mouse is over the iframe the mouse-wheel scroll won’t work (i suppose it’s trying to scroll within the iframe? Any way around this?

    Reply
  3. NACVLIA
    Posted on January 18, 2012 at 21:20 Permalink

    HI! i used your script in my new project and have a problem. i use the scriller to display content wich appears after clicking a search button and the scroller isnt there,but if i zoom the page,scroller appears. can help?

    Reply
    • malihu
      Posted on January 19, 2012 at 21:04 Permalink

      Hi, please check the section “Dynamically loaded content”. You need to recall mCustomScrollbar each time you load new content and after content is actually loaded.

      Reply
      • NACVLIA
        Posted on January 20, 2012 at 22:07 Permalink

        instead of text i have this: when you enter the page the content and the scroller isnt there but if you click the search button the content appears without scroller.i tried to use the section you told me and wrote .Results instead of “new.html” the scroller appeard without content and after clicking search it appeard but scroller is unmovable.If you can tell me right way i added my testing website in this comment

        Reply
  4. Robert Branton
    Posted on January 15, 2012 at 21:39 Permalink

    I like your JQuery scroller but there is a problem with IE9 that causes the last element in a Horizontal scroller to wrap round onto a second line.
    Same think happens in your Demo.
    Is this a known bug?
    Thanks

    Reply
    • malihu
      Posted on January 16, 2012 at 00:02 Permalink

      Hi Robert,
      I’ve just checked the demo (http://manos.malihu.gr/tuts/jquery_custom_scrollbar.html) on IE version 9.0.8.112 on windows 7 and I don’t see any issues. Can you provide IE9 version and OS?
      Thanks

      Reply
      • Robert Branton
        Posted on January 17, 2012 at 17:35 Permalink

        The error is using IE version 9.0.8.112 on Windows Vista Home Premium.
        If you let me have an address, I can email you a screen image.
        The problem is ‘fixed’ if I add a space + nbsp to the end of the contents – which implies that the div width is not being calculated correctly.
        R

        Reply
        • Victor
          Posted on September 10, 2012 at 19:31 Permalink

          I have the same problem with Internet Explorer 9, version 9.08112. Robert Branton’s “fix” resolves the problem. Is there a real fix?

          Reply
          • malihu
            Posted on September 10, 2012 at 23:41 Permalink

            If you’re using the old plugin version, try implementing version 2 as it handles better auto-expanding horizontal scrollbars and eliminates such issues.

          • Victor
            Posted on September 14, 2012 at 00:52 Permalink

            I’m using the latest version. An &npsb it’s not such a big deal:)

            Thank you for a great plugin.

    • malihu
      Posted on January 19, 2012 at 21:15 Permalink

      manos AT malihu DOT gr

      Reply
  5. Simon Dau
    Posted on January 15, 2012 at 18:56 Permalink

    hi there.

    Just wanted to let you know I have published an article about your custom scroller over in kartogram’s blog. This time some mobile functionality was added to extend usability of this brilliant pllugin.

    Simon

    Reply
  6. Vladimir Varbanov
    Posted on January 10, 2012 at 10:33 Permalink

    Hello,
    thanks for this awesome plug-in!
    I’ve just installed and adjusted the horizontal scroll, but not every time is working actually. For example on refresh – there is no working – the content div displaying the images in one long column and there is no scroll controls and scrolling actually.

    No errors in the console..
    visiting the page from other document reference the scroll is working on Safari, but on Firefox the last picture is always on a new row.

    Will be really thankful of somebody share opinion..

    Reply
  7. ido
    Posted on January 8, 2012 at 16:42 Permalink

    i tried to update jquery from 1.6.2 to 1.7.1

    the mousewheel broke doesn’t work anymore…

    Reply
  8. Lee
    Posted on January 7, 2012 at 03:14 Permalink

    Thank you for the examples. Really nice and very useful content. I was trying to implement to my website. Everything seems fine except the scroll bar is not moving. I couldn’t scroll it down to see the content. Do you have any idea what may cause that happen? I couldn’t figure it out.

    Any help would be appreciated
    Thank You.

    Reply
    • Lee
      Posted on January 7, 2012 at 03:56 Permalink

      I forgot to mention i am using MAC computer. Is that why the scroll bar is not moving at all? I read the previous posts and did the changes like below but it’s still not working.

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

      Any helps?

      Reply
      • malihu
        Posted on January 19, 2012 at 21:18 Permalink

        Shouldn’t be a Mac related issue but I’d need to check the actual link. Can you send it via e-mail?

        Reply
  9. von
    Posted on January 6, 2012 at 19:08 Permalink

    is there any formula for the buttons if you click them up/down and the scroll amount of the content is fixed?

    Example:

    If you click on the top and down arrow buttons the content moves 300px up and down?

    Any help would be greatly appreciated. Thanks

    Reply
  10. Chris
    Posted on January 3, 2012 at 20:31 Permalink

    This is exactly what I’ve been looking for but I can’t seem to get it to work correctly- I placed it in as you suggested, the only change I made was that I linked the CSS and JS files and I changed the container color to #333 because the type was white with a white background and couldn’t see it.
    here is a link to the test page I created to see if I could get it working, there’s not much in there so I’m not sure what the issue is.
    http://mangonyc.com/scrolltest/scrolltest2.html

    Any help would be appreciated
    Thanks

    Reply
    • taylor
      Posted on January 4, 2012 at 05:50 Permalink

      Chris,

      I’m new at this but I’ve been messing with it today and have it working. I think you’re missing the bit that includes the custom scrollbar plugin (jquery.mCustomScrollbar.js). Insert this at the end of your document, just before the closing body tag.

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

      And big thanks to Malihu! I’m replacing some old flash code that had a nice little scroll bar. This is just what I needed.

      Reply
      • taylor
        Posted on January 4, 2012 at 05:55 Permalink

        Whoops. There should be more to that but the script tags got stripped out. Do a search on this page for:

        The final step is to include the actual custom scrollbar plugin (jquery.mCustomScrollbar.js) and the function that calls and configures the scrollbar(s) at the end of your document, just before the closing body tag.

        That’s where he gives the instruction.

        Reply
  11. LuXiFeR
    Posted on January 3, 2012 at 12:36 Permalink

    Amazing scrollbar!!
    I’ll use on a website for one of my client. It works fine on all browser but i’ve got one little problem on chrome. The fact is when I click the dragger and drag it down or up and the cursor hover the scrollable content, then the browser select the content. So I juste add one little event to prevent this side effect.

    $('.dragger').bind('mousedown', function(event) { event.preventDefault(); });

    Reply
  12. Alan M. Maziero
    Posted on January 2, 2012 at 21:48 Permalink

    Hello, firstly my thanks to Malihu for his beautiful script, it helped me some times.
    But this time I had to employ that scrollTo function, and searched everywhere for a replacement script, but not found 🙁
    The closest i found was this one: MopSlider 2.5 Demo, with beautiful draggable content (a feature that i wanted to my project), synched with scrollbar, but.. well, its documentation is a little hard to follow and seems not support content refreshing.

    So i came to this solution, it’s nothing genial but works, considering my absolute lack of intimacy with mathematics:

    (It’s to be used with horizontal scrolling):

    function jscrollHor(jqel){
    //jqel is the jquery element to be tracked
    //(ex: $(“#mcs_container .content #myanchor”);

    var trgt = jqel;

    var margin = 30; // offset in pixels to give a little breath before content
    var c_totalWt = $(“#mcs_container”).find(‘.container’).width(); //total width of content
    var c_obj_pos_abs = $(trgt).position().left – margin; // the abs position of anchor inside the content
    var c_obj_pos_rel = c_obj_pos_abs * 100 / c_totalWt; // the relative position of anchor to content

    var d_totalWt = $(“#mcs_container”).find(‘.dragger_container’).width(); //the total width of scrollbar
    var d_pos_rel = (d_totalWt * c_obj_pos_rel) / 100; // the new position of dragger relative to scrollbar

    //and then, we apply these values

    $(“#mcs_container”).find(‘.container’).animate({left:’-‘+c_obj_pos_abs + ‘px’},’fast’,’expoEaseOut’);
    $(“#mcs_container”).find(‘.dragger’).animate({left:d_pos_rel + ‘px’},’fast’,’expoEaseOut’);

    }

    Hope it helps someone 🙂

    Reply
  13. von
    Posted on January 2, 2012 at 09:32 Permalink

    Hi. Thank you for this plugin

    Is there any way to adjust the number of pixels moved by the content when clicking the arrow button? Thanks a lot

    Reply
  14. fefe
    Posted on December 31, 2011 at 12:37 Permalink

    Hi!

    First of all thanks for this amazing plugin. I have been implementing with a joomla site. Everything is working fine but with opera and internet explorer I’m facing probems. Internet explorer 9 dies on page load and sometimes opera is not calling the scroller. Has anybody had the same behaviour? Is there a workaround for this issue?

    Reply
  15. Gabriele
    Posted on December 27, 2011 at 15:30 Permalink

    your plugin is awesome!!
    i’ve already deployed it onto my website!!
    thanks a lot!!

    Reply
  16. Martin
    Posted on December 26, 2011 at 19:21 Permalink

    TOUCH SUPPORT FOR IPAD/MOBILE DEVICES?

    Reply
  17. lior
    Posted on December 26, 2011 at 18:13 Permalink

    Hello malihu,
    i am using your custom scrollbar and Quicksand.
    after filtering items in each content area and resizeing my Window
    scrollbar height/width adjustment (values: “auto” or “fixed”) not helps!
    please helpe!

    Reply
  18. Peter Szekeres
    Posted on December 25, 2011 at 15:37 Permalink

    Hi I made a kind of scrollToBottom() function, can be useful for chatwindows:

    $(“#mcs_container”).mCustomScrollbar(“vertical”,400,”easeOutCirc”,1.05,”auto”,”yes”,”yes”,10);

    var topD=$(“#mcs_container .dragger_container”).height()-$(“#mcs_container .dragger”).height();

    $(“#mcs_container .dragger”).css(‘top’, topD+’px’);

    var topC=$(“#mcs_container .customScrollBox”).height()-$(“#mcs_container .container”).height();

    $(“#mcs_container .container”).css(‘top’, topC+’px’);

    Reply
  19. Fer
    Posted on December 20, 2011 at 16:06 Permalink

    Hi,
    Thank you for sharing this cool script.
    I have one question though:
    Is there a way of adding a fixed space (top and bottom), so when you scroll the content has some ‘air’ ?
    For example, if you have a header and then a long list of elements, I can have a padding for the first element, but when I scroll down, the list would be too close to the header.
    I would really appreciate if you could help on this… I tried several things but can’t find a proper solution.

    Thanks!
    Greetings!

    Reply
  20. Jason
    Posted on December 15, 2011 at 16:31 Permalink

    Hey, I have a little problem. Everything works like it should but I have it so the mcs5_container div doesnt show right away. It is initially “display: none.” I make it so when the user clicks on a tab it will fade in but when that happens, it does not fade in correctly. Everything is vertical with no scroll or anything. It looks completely different. Can you help?

    Reply
    • Jason
      Posted on December 15, 2011 at 19:22 Permalink

      I just found out it works correctly within Dreamweaver when I click on “live view” but it does not work when I preview it in any browser.

      Reply
  21. digi
    Posted on December 15, 2011 at 07:08 Permalink

    very nice plugin!

    I’ve seem to run into a minor problem though. When i scroll down, my content gets pushed down instead of up. It’s scrolling the wrong way basically. If that makes any sense.

    Any idea why? Been trying to figure it out for hours.

    Reply
    • Bob
      Posted on February 6, 2012 at 00:55 Permalink

      I’m having the same problem. Did you ever get this resolved?

      Reply
      • Bob
        Posted on February 6, 2012 at 02:11 Permalink

        Ok, I figured this out for my scenario. I had to change the name of the .content class to .msContent because I was already using that class name for another part of my code and my CSS declarations were conflicting.

        I had to change line 7:

        var $customScrollBox_content=$("#"+id+" .customScrollBox .content");

        To:

        var $customScrollBox_content=$("#"+id+" .customScrollBox .mcsContent");

        Now it works perfectly.

        Great script!!

        Reply
      • Bob
        Posted on February 6, 2012 at 02:12 Permalink

        That’s line 7 in the jquery.mCustomScrollbar.js script.

        Reply
  22. Martin
    Posted on December 15, 2011 at 05:35 Permalink

    Hi, excellent work. There is a possibility to slide the content by dragging the content lije touch sceen? And 2nd: there is a possibility to add touch support? Thanks.

    Reply
  23. Jay B
    Posted on December 12, 2011 at 22:09 Permalink

    Hey,

    Absolutely love this scrollbar! I’ve been looking for a good one for some time and found this and have been nothing but impressed – great job! I am running into one problem, and I read through a lot of the posts and didn’t see this, so I’m asking for some help. I am using this scroll on a page that has tabbed content. On the first tab, the scroll bar works perfectly. Now, I tried adding multiple scrolls as suggested (unique id – even some of the classes where I could get away with it) and when I nav. off the first tab, the bar either doesn’t appear, or if I change the scroll time in the function call to “a” (any letter) instead of a number, it will show, but not work. I have tirelessly looked over every letter of all associated code and I think at this point I have done what I can to figure this out. Any ideas? Sorry for the book, I really hope to get this to work. Your time is greatly appreciated!

    Link to demo page for you to view:
    http://www.dqrm.com/demo/TFD2.htm

    ~J

    Reply
    • malihu
      Posted on January 11, 2012 at 15:42 Permalink

      Hi,
      You need to re-call mCustomScrollbar function each time new content is loaded (in your case each time a new tab is clicked). Please check section Dynamically loaded content on this post to get an idea on how to apply it to your page.

      Reply
  24. Elvis
    Posted on December 9, 2011 at 17:50 Permalink

    Hi!

    I’m trying to load this scroller inside fancybox, but javascript is probably not loaded when I open fancybox popup. I’m too weak in jQuery to find out, which part of the code must I change to make it work, I tried with .ready events but no success.

    Any help would be greatly appreciated!

    Reply
  25. fefe
    Posted on December 7, 2011 at 01:14 Permalink

    First of all thank you for this great plug in! I’m trying to implement with a joomla site but I’m facing a problem with the mouse wheel. Doesn’t want to fire up.
    Has anybody get it to work in joomla environment?

    http://www.css-teske.de/portal

    Reply
  26. Mathias
    Posted on December 6, 2011 at 13:01 Permalink

    hi,

    great work! just found a little bug only showing up in ie(tested on ie8), that’s easy to resolve:
    in the horizontal slider example, the images are dropping out of the container.

    with #mcs_container .content image{float:left} this can be fixed

    Reply
  27. Mike Shenker
    Posted on December 5, 2011 at 15:30 Permalink

    Hi!

    I wonder which will be the easiest way to have an initial variable scroll. I’ve seen in the comments above some snippets to set an initial scroll but it was a fixed amount.

    I need this to keep the scroll in a vertical menu after clicking on a link (which opens a new page and obviously clears the scroll).

    Thanks in advance!

    Reply
  28. Hugo Shelley
    Posted on December 2, 2011 at 21:53 Permalink

    Can you have an adjustable scroller width in horizontal orientation? If the dragger container is set to 100% it will scale to the width of the horizontal wrapper (ie the width of the content) not to the width of the screen …

    Would be very grateful for any advice. Thanks!

    Reply
  29. Sarees
    Posted on December 2, 2011 at 11:18 Permalink

    really great stuff for developers this script for custom content scroller will really helpful also we can suggest this thing to our developers too. great article.

    Reply
  30. conceptskip
    Posted on November 28, 2011 at 17:20 Permalink

    Hello,

    first of all, thank you for this great plugin. I searched around the web a lot for a stylish scrollbar, and this definitely is the best one.

    I’d like to confirm two of the previous posters:
    @rareseeds: I had Jquery 1.7.2 loaded and the mousewheel didnt work, changing it back to 1.6.4 really helped out.

    @Fred: i also use use several divs inside the mcs_container_content and ran into the problem of malfunctioning scolling, therefore i replaced line 195:
    var totalContent=$customScrollBox_content.height();
    with a function to determine the height of the longest div inside the content_container.

    Now it works perfect!

    Chris

    Reply
    • lior
      Posted on December 26, 2011 at 18:22 Permalink

      hi there
      i think i have the same broblem
      again what did you do to solv it ?

      Reply

Comments pages: 1 8 9 10 11 12 83

Post a comment

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