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,580 Comments

Post a comment

Comments pages: 1 6 7 8 9 10 83

  1. Tracey Williams
    Posted on October 13, 2011 at 01:43 Permalink

    Cannot get the scroller to work, don’t get what is wrong added all the code. Any help?

    Thanks
    TW

    Reply
  2. special monkey
    Posted on October 12, 2011 at 03:49 Permalink

    Wow – Great demo! Still generating interest.

    I want to use it for my photo website (specifically the thumbnail horizontal scroller at bottom) though I would like it if I could also drag the strip of images (e.g. click anywhere on any of the images and pull left or right, ideally locking on a fixed vertical axis so as not to cut off the image if dragging up or down) – is this possible?

    Thanks,
    sm

    Reply
    • Maxime
      Posted on October 13, 2011 at 03:08 Permalink

      Hi all;
      Just in love with that plugin !!and congrats for all that amazing code;
      I’ve read all the post from the beginning and still missing something,

      I’m trying to display 2 customs scrollbar with “the same css style” in the same page :
      to make it simple i used the example provide in the demo
      i liked the style of the div ” mcs3_container
      so i ve duplicated it and named it div “mcs6_container” to keep “unique Id”
      then applied the same structure

      check out the link

      Only the”Adjustable scroller height with 1/3 range ” have to be check
      -the first on works fine
      -the second one can’t scroll ?

      any idea?

      i ve used this script on the html page:
      $(window).load(function() { mCustomScrollbars(); $("#mcs6_container").mCustomScrollbar(); });

      For the Css part
      i’ve gave the almost same style ( except the position on the container )
      to #mcs3_container and #mcs6_container

      any word would be really appreciated
      Regards.

      Reply
    • malihu
      Posted on October 15, 2011 at 15:10 Permalink

      You might find http://manos.malihu.gr/jquery-thumbnail-scroller better for what you wanna do (if you don’t need scrollbars etc.)

      Reply
  3. idris
    Posted on October 9, 2011 at 21:13 Permalink

    i seriously wanted this one…u r life saver…thank you so much for sharing

    Reply
  4. Brother Dominic
    Posted on October 6, 2011 at 15:27 Permalink

    Hi malihu,

    I have got the vertical scroller working very well here:http://www.papastronsay.com/prayers – THANK YOU for all your hard work.

    Problem: the arrows don’t line up with the scroller. I’ve tried hacking the css to no avail. Any ideas? It would help a lot to make my page look better.

    God bless,

    Br Dominic Mary, F.SS.R.

    Reply
    • malihu
      Posted on October 8, 2011 at 17:16 Permalink

      Just increase a bit the margin-right values of scrollUpBtn and scrollDownBtn anchors.

      Reply
  5. Rene
    Posted on October 6, 2011 at 00:14 Permalink

    I cannot get the scroller to start at 200px instead of 0px, so the user can scroll left or right.
    Adding a Left in the CSS for the dragger does nothing.
    or maybe I’m placing the ScrollX(); in the wrong spot. In an earlier post you said to place it at line 142, which breaks the code, and is ‘before’ the Scroll function. so I’m confused. Please help.
    Thanks so much!!

    Reply
    • Rene
      Posted on October 6, 2011 at 22:39 Permalink

      I got it to work.
      I just had to remove #mcs5_container 🙂

      Reply
  6. Ben
    Posted on October 4, 2011 at 20:05 Permalink

    This is great and nice jquery add on. Thank to you for create such a wonderful tools. I have try to my website and it works fine in 32bit machine including Mac Lion, but windows 64bit is giving me an headache (all browser IE9, FF, chrome)
    this is error, I found

    Message: Expected ‘)’
    Line: 12
    Char: 312
    Code: 0
    URI: http://ajax.googleapis.com/ajax/libs/jqueryui/1.8/jquery-ui.min.js

    Message: Object doesn’t support this property or method
    Line: 211
    Char: 5
    Code: 0
    URI: http://www.bluecube.com.sg/internal/metaphor/wp-content/themes/metaphor/js/jquery_custom_scroller/jquery.mCustomScrollbar.js

    Appreciate your help! Thank you!

    Reply
  7. Nael
    Posted on October 2, 2011 at 17:16 Permalink

    Hello,

    first of all, thank you for you great scroll tools.

    I have a little prob using the auto-adjustable horizontal srcoll (horWrapper) :

    It works fine on Chros and Safari, but I sometimes ave a little surprise on firefox (6.0.2 and 7.0.1) and internet explorer 9.
    Sometimes one image of my horizontal scroll goes to line. it’s very strange.
    If i delete one image or add one image on the container, it works fine.

    here is an exemple of the problem :

    http://nathanael.brun.free.fr/remove/test_php/exemple_horwrapper_prob.php

    I’m not an expert, I only try to develop a website with what I find and try to understand things as i go, so I may have done some mystakes that I don’t understand.

    thanks,

    Nael

    Reply
    • Hoyt
      Posted on October 6, 2011 at 23:29 Permalink

      Hi,
      I face the same thing in my firefox version 3.6.23 and OK in other browsers. I think it is because of the mis-match between the plugin and the browser.

      In my case i just increase the width of the horWrapper by 1 pixel (do this in the .js )then the last image is able to display inline.

      Thanks to Manos too.

      Reply
      • malihu
        Posted on October 8, 2011 at 17:10 Permalink

        Hi Hoyt,
        Check the quick fix below as it should also work in your case.

        Reply
    • malihu
      Posted on October 8, 2011 at 17:05 Permalink

      Hi Nael,

      This happens because of the whitespace added by browsers on inline-block elements (a space separating each inline element like words, images etc.).

      A really quick fix is to remove any spaces or new lines between your img elements in your html document. For example this:
      <img src="pripyat_fichiers/images/chernobyl-01-eng.png " alt="Chernobyl map"/> <img src="pripyat_fichiers/images/chernobyl_pripyat-entry.jpg " alt="Chernobyl Pripyat"/>
      should be:
      <img src="pripyat_fichiers/images/chernobyl-01-eng.png " alt="Chernobyl map"/><img src="pripyat_fichiers/images/chernobyl_pripyat-entry.jpg " alt="Chernobyl Pripyat"/>

      Reply
      • Nael
        Posted on October 28, 2011 at 17:54 Permalink

        I removed the new line before the last image and it works fine ! thank you Malihu.

        Reply
  8. Gianni
    Posted on September 30, 2011 at 16:05 Permalink

    Well done!
    I started from your work for scrollbars used in Uefa MatchCentre:
    http://www.uefa.com/uefachampionsleague/season=2012/matches/live/index.html?day=2&session=1&match=2007586#previous

    Reply
    • malihu
      Posted on October 8, 2011 at 16:39 Permalink

      Cool 😀 Thanks for posting!

      Reply
  9. Amy
    Posted on September 29, 2011 at 02:26 Permalink

    Hi – I’ve customized your scrollbar – and it looks great.
    However I can’t get it to actually scroll.
    Can you please take a look?
    http://www.centerenrichment.org/final/mission2.html

    p.s. I’m on a Mac – if that make any difference.
    Thanks
    Amy

    Reply
    • Amy
      Posted on September 29, 2011 at 03:57 Permalink

      I dug through my coade and realized that the scroll isn’t working because I am using another Jquery code on the same page. It is PrettyPhoto.

      Pretty photo uses:
      “https://ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js”

      and the Custom Scroll uses:
      “http://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js”

      Is there any way to make them both use the same reference so that they don’t cancel eachother out?

      Reply
  10. Harshil Shukla
    Posted on September 28, 2011 at 09:55 Permalink

    I would like to fix the header of the table and rest of the content should be scrollable. Currently I am using your script for scrolling the table which is scrolling header and data too. How to make header as fixed ?? I really need help on this.

    Reply
  11. Timmy
    Posted on September 27, 2011 at 15:29 Permalink

    Hi,
    I also like to use your script – used once or twice in projects.
    Now I used it again and it does not scroll up when I drag the dragger down,
    it scrolls with the dragger… but I implemented it as stated here and as I did before.
    Any Ideas?

    Greets Timmy

    Reply
  12. Miguel López Pinedo
    Posted on September 27, 2011 at 09:50 Permalink

    You rocks mate.
    I got some problems to resize after I put the content to appear after a jQuery animation but finally I solved with your LoadNewContent after the animation complete.
    Thanks a lot.

    Reply
  13. Goksel
    Posted on September 24, 2011 at 03:25 Permalink

    Great post man!
    An addition script to plugin for whom want to scroll to a specific item on load :
    function scrollToItem(item){ var n = item.position().top - 20; var c = $(".container"); var c_h = c.height(); var d = $(".dragger"); var d_h = $(".dragger_container").height(); var d_p = parseInt(n*d_h/c_h); c.animate({top: -n},1000); d.animate({top : d_p},1000); } $().ready(function(){ scrollToItem($("#div1")); });

    Reply
    • Mike
      Posted on November 11, 2011 at 04:34 Permalink

      How did you determine the -20 on var n?

      Reply
    • fab
      Posted on June 21, 2012 at 15:35 Permalink

      Thank you very much for this function.
      That’s what i was looking for. It works nice for me.

      Reply
  14. sTEk
    Posted on September 23, 2011 at 15:42 Permalink

    @GeneC
    I’ve got this prblem to. Do you have only DIVs in yur content-box?

    Reply
  15. Reem
    Posted on September 23, 2011 at 02:49 Permalink

    For everyone who have problem of size when loading new content to vertical scroller, add this line:

    scrollAmount=($customScrollBox_content.height()-(visibleHeight/bottomSpace))/(draggerContainerHeight-draggerHeight);

    at the beginning of Scroll() function

    Reply
  16. Gene C
    Posted on September 20, 2011 at 23:16 Permalink

    Hello,

    Thank you for this wonderful scroller. Very polished work. Just one problem, when I implemented it on my site, the scrolling behavior was inverted. When I drag the scrollbar down, instead of moving the page up, it goes down. I used your example in “jquery_custom_scrollbar_vertical_full.html”, which works in the demo, but not on my site. I made sure to include all the correct elements. I even tried different config options. What could be causing this?

    Thank you !!

    Reply
  17. Dingbat
    Posted on September 20, 2011 at 10:17 Permalink

    Hi there, excellent stuff. Thanks.
    However, i encountered that on some days the css or the script not working while at some other times, it works perfectly fine. is it due to the ‘http://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js’ script where the script was hosted that the page is down or something? Please advise. Thanks

    Reply
    • malihu
      Posted on September 20, 2011 at 11:09 Permalink

      Hi, I don’t know if the reason was google CDN was down but here’s a code to use for loading jquery from google with a fallback to local:
      <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.6/jquery.min.js"></script> <script>!window.jQuery && document.write(unescape('%3Cscript src="js/jquery-1.6.1.min.js"%3E%3C/script%3E'))</script>
      The example above asumes you have “js” directory where a local copy of jquery (jquery-1.6.1.min.js) resides.

      Reply
      • Dingbat
        Posted on September 21, 2011 at 05:16 Permalink

        Hi Malihu, appreciate your help. Thanks. However, the scrollbars still don’t work. I noticed in the demo that the following scripts includes ‘1.4/jquery.min.js’ , ‘jquery.easing.1.3.js’ and ‘1.8/jquery-ui.min.js’. But it didn’t mention anything about ver 1.6.1. as you described in your above solution. Could this be the cause? please advise thanks.
        I think this bug needs to be fixed in the demo as well.

        Reply
      • Dingbat
        Posted on September 21, 2011 at 06:47 Permalink

        Hi again, just an observation that I’ve made. I’ve used the script for 2 different websites and whenever I noticed that the demo in this page do not work, the scroll bars on both my websites do not work as well- even when the sites are run on my local computer. I suspect that something online is causing this issue. I hope you can look into this? thanks! Other than this issue, i think it’s a great application. 🙂

        Reply
      • Dingbat
        Posted on September 21, 2011 at 10:13 Permalink

        Hi, finally got it working. I added the following script to get it working locally:

        !window.jQuery && document.write(unescape(‘%3Cscript src=”jquery-1.6.4.min.js”%3E%3C/script%3E’))

        !window.jQuery && document.write(unescape(‘%3Cscript src=”jquery-ui-1.8.16.min.js”%3E%3C/script%3E’))

        Thanks for your time!

        Reply
  18. Dan
    Posted on September 17, 2011 at 17:17 Permalink

    I carn’t seem to get this to work on my computer!
    I keep getting 1 error from the jquery.mCustomscrollbar document saying

    $dragger.draggable is not a function
    [Break On This Error] stop: function(event, ui) {

    so I carnt move my dragger anywhere!

    I’ve copied the whole thing word for word mulitple times and its just not working but it seems to be working fine for you. help. :'(

    Reply
  19. Koen
    Posted on September 17, 2011 at 00:00 Permalink

    Hello,

    Thank you for the nice script.

    Is there a way to manipulate the start position or automaticly scroll to a (variable) position when te page loads ?

    I have a page with 15 static thumbs. When a thumb is pushed i jump to a page with your (horizontal) scroller containing 15 big images in one row. I’ll get a position-var true the url (like page.html ?scrollerposition=1200). Is it possible that the scroller scroll to this (variable) position ???

    THX !!!

    Reply
  20. zane
    Posted on September 16, 2011 at 22:41 Permalink

    Why on earth are you passing parameters into your function vs. using a more traditional jQuery plugin approach of using “options”?

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

    vs.

    $(“#mcs_container”).mCustomScrollbar({
    “vertical”: true,
    “easeOutCirc”: 1.05,
    “auto”: true,
    …. and so on
    });

    Reply
    • malihu
      Posted on September 19, 2011 at 12:29 Permalink

      When I wrote the script, I didn’t want to clutter the code when having multiple version of the scroller on the same page (just so the code would be shorter). That’s not the best of practices I know. I’ve been meaning to update the plugin to pass parameters as options (among others) but I work like crazy and haven’t got the time to do so (yet).

      Reply
      • zane matthew
        Posted on September 19, 2011 at 21:54 Permalink

        If you put it on github I wouldn’t mind taking a crack at it 😉

        Reply
  21. Sergio
    Posted on September 15, 2011 at 09:47 Permalink

    Hi Man!
    I like the scrollbars very much, but i have an issue.
    I tryied to implemente at the same time the scrollbars, a page fade and lightbox, and i discovered when the lightbox is added, the scrollbars doesn’t work.
    Please help me with this issue.
    you can see it at http://www.dinamoarquitectura.com/test/proyecto1.html
    Thankx a lot!

    Reply
  22. Carlos
    Posted on September 13, 2011 at 19:18 Permalink

    Hi, I had trouble trying to implement your script anchors would like to see how you could do to go to the top with a single click with a aclanje.

    And another development is that it does not work for me via the scroll key, take this example but it did not work.

    $ (document). keydown (function (e) {

    if (e.keyCode == 38) {
    $ (“. ScrollUpBtn”). Mousedown ();
    setTimeout (“$(‘. scrollUpBtn ‘). mouseup () “, 250);
    }

    if (e.keyCode == 40) {
    $ (“. ScrollDownBtn”). Mousedown ();
    setTimeout (“$(‘. scrollDownBtn ‘). mouseup () “, 250);
    }

    });

    In advance thank you very much:)

    Carlos Molina

    Reply
  23. Achna
    Posted on September 13, 2011 at 18:30 Permalink

    Hello Malihu,

    Great work, using it for my college project.

    One of my HTML page has lot of content so I used TOC type linking.
    TOC heading are (links) placed on the left side, and the right side has content. These links are the anchor, clicking on these links scroll up/down the right side of content area to the respective topic heading. This content is tagged inside the “”, however when I click on the link whole scrollbar move up. Can you please help?

    Thanks

    Reply
  24. Abraham CC
    Posted on September 8, 2011 at 03:55 Permalink

    Hi! Amazing job.

    I’m implementing this in my personal tumblr theme, changing the scrolls.

    My problem is that I want to make this:

    custom scroll
    >>nested custom scroll

    <!--nested custom scroll--> <!--/nested-->

    and then:

    jQuery(window).load(function() { jQuery("#mcs1_container").mCustomScrollbar("vertical",150,"easeOutCirc",1.05,"fixed","yes","no",0); jQuery("#mcs2_container").mCustomScrollbar("vertical",jQuery(window).height(),"easeOutCirc",0,"fixed","yes","no",0); });

    It works just with one custom scroll… when I open a link with nested custom scroll, both works like one :S, the nested scroll have the control of the drag…

    Any way to get it?

    Sorry for my bad english, I’m learning… Thanks.

    Reply
  25. Eddie Reyes
    Posted on September 7, 2011 at 02:50 Permalink

    Forgot to reference page so you can see the problem:

    http://wilshirerestaurant.com/bio-test/

    Reply
  26. Eddie Reyes
    Posted on September 7, 2011 at 02:48 Permalink

    ( Forget to reference the problem page:
    http://wilshirerestaurant.com/bio-test/ )
    What an awesome scrollbar you’ve made! Thank you!

    I’m having a weird thing happen though: as one brings the scroll button back up, I never get back to the initial starting place and opening text is cut off and starts later:

    In webkit I see this when I bring the scroller back to the top:

    The “top: -231px;” is the problem. Initially on page load that code is:

    Any thoughts?

    Thanks

    Eddie

    Reply
  27. Eddie Reyes
    Posted on September 7, 2011 at 02:46 Permalink

    What an awesome scrollbar you’ve made! Thank you!

    I’m having a weird thing happen though: as one brings the scroll button back up, I never get back to the initial starting place and opening text is cut off and starts later:

    In webkit I see this when I bring the scroller back to the top:

    (I added the style inline)

    The “top: -231px;” is the problem. Initially on page load that code is:

    Any thoughts?

    Thanks!

    Eddie

    Reply
  28. okan bircan
    Posted on September 7, 2011 at 01:30 Permalink

    Great job! awesome! thanks

    Reply
  29. Simon Dau
    Posted on September 6, 2011 at 01:47 Permalink

    Excellent plug-in! I have used it in my website (click the name to check it if any interest). As there are quite few question within comment section to add additional functionality of custom scrolling etc. I have written a short blog post about how to do it. It can be found here:
    http://www.blog.kartogram.co.uk/post.cfm/custom-functionality-for-custom-scrollbar
    Again, thanks a lot! brilliant project.
    cheers,
    SD

    Reply
    • malihu
      Posted on September 10, 2011 at 15:43 Permalink

      Fantastic 🙂 Thank you Simon.

      Reply
    • Kaiser_Soze
      Posted on November 24, 2011 at 23:26 Permalink

      Many praises to Simon Dau for the added feature and Malihu for this awesome plugin! I was about to give up hope on a scrollto anchor-like navigation within mCustomScrollbar and am damn glad I read through all of these comments to find this!

      Awesome! Saved me a ton of time!

      Reply
  30. Alex
    Posted on September 5, 2011 at 19:35 Permalink

    Is there a way to validate the contents of ? W3V says that style tag is not permitted to sit where it sits now. Thanks.

    Reply

Comments pages: 1 6 7 8 9 10 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