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.0.7 (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).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 on $(window).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).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.
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.
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).
advanced:{ autoExpandHorizontalScroll: boolean }
Auto-expand content horizontally (for "x" or "yx" axis).
If set to true, content will expand horizontally to accomodate any floated/inline-block elements.
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.
The value should be true (default) when your content contains images.
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:{ releaseDraggableSelectors: "string" }
Add extra selector(s) that’ll release scrollbar dragging upon mouseup, pointerup, touchend etc.
Example: releaseDraggableSelectors: ".myClass, #myID"
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:{
      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:{
      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 accomodate 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(pos>=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");

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

Post a comment

Comments pages: 1 57 58 59

  1. jinendra
    Posted on January 29, 2015 at 12:46 Permalink

    how to remove special annimation effects while scrolling

    Reply
    • malihu
      Posted on January 29, 2015 at 13:39 Permalink

      See scrollInertia option paraneter. You can set it to zero like this:
      $(selector).mCustomScrollbar({ scrollInertia: 0 });

      Reply
      • jinendra
        Posted on January 29, 2015 at 13:56 Permalink

        i tried that but scroll is too slow i need normal speed

        Reply
        • jinendra
          Posted on January 29, 2015 at 14:02 Permalink

          i need normal scroll speed i need to remove speed delay of scroll

          Reply
  2. thegrandwizard
    Posted on January 28, 2015 at 18:12 Permalink

    Hi

    I’ve used your plugin on a site and everything works nice. However i have a question regarding the scrollto method. I would like to scroll to an id plus lets say 100px. How is it possible to achieve something like this?

    $(selector).mCustomScrollbar(“scrollTo”,”#el-1″); // + 100px

    Thanks for your help.

    Reply
    • malihu
      Posted on January 28, 2015 at 18:31 Permalink

      Hi,

      You’ll need to get the target element’s position and then add (or subtract) the pixels number to offset scroll-to.

      For example, assuming you have a link with id “st-link” and your target element id is “st-target”, you can do:
      $("#st-link").click(function(e){ e.preventDefault(); var offset=100, target=$("#st-target"), to=(target.offset().top-target.parents(".mCSB_container").offset().top)+offset; $(selector).mCustomScrollbar("scrollTo",to); });

      Let me know if this helps

      Reply
      • thegrandwizard
        Posted on January 29, 2015 at 11:43 Permalink

        Hi malihu

        I wasnt expecting such a fast reply. Thank you very much for you help. It worked perfectly.

        Reply
        • malihu
          Posted on January 29, 2015 at 11:57 Permalink

          Great! You’re welcome :)

          Reply
  3. Mav
    Posted on January 28, 2015 at 13:44 Permalink

    Hi, great plugin, many thanks for sharing.
    I’ve just got one simple issue on particular browser: mobile chrome. Seems to work on defaul android device and iphone safari.
    Namely I only use horizontal scrollbar, but when I try to verticaly scroll(swipe) from within the scrolling content page is stuck. I can still scroll by swiping outside of scrolling content, but it is not satisfactory for my client I am afraid. Any ideas?
    There is an example:
    http://apollonew.websitedesigntest.co.uk/View/3/42/1136/category/bassano/Apollo-bassano-vertical-round-designer-radiator

    Reply
    • malihu
      Posted on January 28, 2015 at 14:14 Permalink

      Thanks for the feedback! I’m afraid there’s no solution for this at the moment. I’ll need to investigate the issue and try to apply a fix on the next plugin version.

      Reply
      • Mav
        Posted on January 28, 2015 at 14:54 Permalink

        Thanks, great work anyway.

        Reply
  4. Sajidur Rahman
    Posted on January 28, 2015 at 10:19 Permalink

    Pure perfection. Also works great on mobile device. Thank you so much. You are awesome <3

    Reply
  5. Brett Schumann
    Posted on January 27, 2015 at 16:25 Permalink

    Thank you for creating this plugin it has been a real life saver. I do have one question which I am hoping that you are able to help with. I am currently using this plugin for menus on our site when the users viewports are smaller than menu heights which is working great.

    What I would like to know is there a way that I can prevent the scroll event from bubbling up. Basically what is happening is that when the user reaches the bottom of the scroll or the top the content of the website is scrolled. I would like to prevent this from happening if the user is scrolling within the menu.

    Once again thank you for the awesome plugin.

    Reply
    • malihu
      Posted on January 27, 2015 at 16:42 Permalink

      Yes of course :)

      Just set the mouseWheel: preventDefault option parameter to false :
      mouseWheel:{ preventDefault: false }

      Reply
      • Brett Schumann
        Posted on January 27, 2015 at 19:33 Permalink

        Yeah I did that but it still works for touches. It seems that touch events still go through to the parent. :(

        Is there something else that I might be missing.

        Reply
        • malihu
          Posted on January 28, 2015 at 04:47 Permalink

          Yes, this option is only for the mouse-wheel.

          The touch events do not have this as it’d be against what users expect from using touch-enabled devices and it could potentially render the whole page unusable.

          For example, if a user is on a low-resolution device and your menu fills the entire viewport (or just most of it), he won’t be able to scroll the page at all.

          If for some reason you still want to do it you’d need to edit the script and remove “e.preventDefault();” from line 1247

          https://github.com/malihu/malihu-custom-scrollbar-plugin/blob/master/jquery.mCustomScrollbar.js#L1247

          Reply
  6. MJ.Saee
    Posted on January 27, 2015 at 06:28 Permalink

    Hi !
    Very Good tutorial.

    Tanks

    Reply
  7. Nadav Rotchild
    Posted on January 23, 2015 at 11:42 Permalink

    Hi. I just wanted to thank you for the great plugin. Worked perfectly out of the box and looks mighty good!

    Reply
    • malihu
      Posted on January 23, 2015 at 12:00 Permalink

      Thanks for your comment :)

      Reply
  8. Nejc
    Posted on January 23, 2015 at 10:06 Permalink

    Hi,

    I am using vertical scroll with stepless scroll buttons, also scrollAmount is set to 80. Now the animation is quite hard, is it possible to make it smoother?

    Thank you for your reply,
    Nejc

    Reply
    • malihu
      Posted on January 23, 2015 at 10:47 Permalink

      Lower the scrollAmount value(?) Why you need it to 80?

      Reply
      • Nejc
        Posted on January 23, 2015 at 14:03 Permalink

        Problem is that this value was set from my employer, because this is desired move on one scroll button click. Now my problem is that I need to create same effect that has function $(selector).mCustomScrollbar(“scrollTo”,position,options); with this scrollAmout.

        Thank you for help,
        Nejc

        Reply
        • malihu
          Posted on January 23, 2015 at 22:16 Permalink

          You can set a specific duration for any scrollTo method call via the scrollInertia method option parameter. For example:
          $(selector).mCustomScrollbar("scrollTo",position,{ scrollInertia:80 });

          Does this help?

          Reply
          • Nejc
            Posted on January 27, 2015 at 23:03 Permalink

            Hi,

            it was not really a solution, but this helped me came up with the idea that employer accepted.

            Thank you for help and awesome plugin,
            Nejc

  9. Mela
    Posted on January 22, 2015 at 06:16 Permalink

    Hi! Thanks for creating this plugin.

    I’m using it for a horizontal content slider. Is there a way to create anchors for the divs inside the scroller? I tried using it the usual way, but if I try it the scrollbar disappears…

    Reply
    • malihu
      Posted on January 22, 2015 at 06:33 Permalink

      Hi,

      Are you trying to add content via js?

      When the scrollbar has initialized, your actual content resides within the div with class “mCSB_container”. So if you’re trying to modify your content, you must target your content via the .mCSB_container selector.

      For example, assuming the element with the scrollbar is .content, you can do:
      $(".content .mCSB_container").append("html");

      Is this what you’re trying to do or are you asking about anchor points? Can you explain a bit the “usual way”?

      Reply
      • Mela
        Posted on January 23, 2015 at 06:32 Permalink

        Hi, sorry for the confusing post. No, I’m not adding content via JS.

        So I have these divs inside my scrollbar and I’ve assigned IDs to them:

        div id=”page1″
        div id=”page2″
        div id=”page3″ etc.

        I’m trying to link to these by linking to

        a href=”#page1″
        a href=”#page2″ etc.

        But the links that get generated don’t seem to play well with the scrollbar. The divs (which are not full page width) will appear on the rightmost side of the screen as if they were floated right, and the scrollbar will disappear. If I attempt to scroll, the window will flick back to the first div in the scrollbar.

        Thanks.

        Reply
        • malihu
          Posted on January 23, 2015 at 07:25 Permalink

          I see. The way you do it works only with browser’s native scrollbar.

          To do the same (and much more) with the custom scrollbar, you need to use plugin’s scrollTo method in your script(s).

          For example you could do with jQuery:
          $("a[href*='#']").click(function(e){ e.preventDefault(); $(selector).mCustomScrollbar("scrollTo", $(this).attr("href")); });

          Reply
          • Mela
            Posted on January 29, 2015 at 01:25 Permalink

            Great, thank you!

  10. Shovan Dhara
    Posted on January 21, 2015 at 15:39 Permalink

    I want to enable both horizontal scroll and vertical scroll in a table wrapper. I am not able to do that with current version of the plugin.. Please help

    Ref code –

    /* == jquery mousewheel plugin == Version: 3.1.12

    CSS –
    .edit-grid-container .edit-grid-table .edit-grid-body {
    height: 350px;
    overflow: hidden;
    border-top: 1px solid #E1E1E1;
    }

    JS –
    this.customscrollbarInit = {
    theme: “dark-2″,
    horizontalScroll: true,
    axis:”yx”,
    advanced: { updateOnContentResize: true, updateOnBrowserResize: true }
    };

    Reply
    • malihu
      Posted on January 21, 2015 at 18:35 Permalink

      I’ll be able to help if you could send me a test page (or link) with this issue.

      Reply
      • shovan
        Posted on January 22, 2015 at 08:50 Permalink

        http://vantage-uat.cushwake.com/

        Goto Result > List
        Then choose Primary Search from Search Filter Tab as – Shopping Center and click on Update search

        Right now there is default scroll in table section.. I want to apply both horiz and vertcl scroll there.

        Reply
        • malihu
          Posted on January 22, 2015 at 09:00 Permalink

          Link doesn’t seem to work

          Reply
  11. Leo
    Posted on January 20, 2015 at 23:59 Permalink

    Hi,

    when i click checkbox,button etc. scroll go up.. help please:)

    Reply
    • malihu
      Posted on January 21, 2015 at 01:11 Permalink

      Hello,

      This usually happens due to some missing CSS rule (e.g. some parent element needing position: relative), but I’d have to see your page to know which one. This results in the “wrong” scrolling position when specific elements gain focus (e.g. clicked).

      The elements that scroll the content to their position when focused are defined in autoScrollOnFocus option parameter. If you can’t find how to modify the CSS, you can always remove the tag (in your case “input”) from the autoScrollOnFocus value.

      Reply
  12. Manuel
    Posted on January 20, 2015 at 17:24 Permalink

    Hi, great plugin!!

    I’ve a problem with my website when I try to open an inline HTML content from a page loaded by AJAX.

    The example is related to this: http://manos.malihu.gr/repository/custom-scrollbar/demo/examples/colorbox_demo.html.

    In my website I have the MAIN page (with all the js and css necessary for the plugin) with an AJAX code for loading the ADD page like this:

    var $data = $(‘#success’);
    $(document).ready(function() {
    $data.load(“add”);
    });

    In the ADD page I add the link for open modal window but it doesn’t work!

    <a href="#inline_content">Inline HTML</a>

    If I instead add the same link to the MAIN page it works without problem and the modal window opens correctly…

    Are there any missing parameters that I must add in order to fix my problem??

    Thanks in advance…

    Manuel

    Reply
    • malihu
      Posted on January 20, 2015 at 18:17 Permalink

      Hello,

      I think your issue is not related to custom scrollbar plugin. It’s more about colorbox plugin and (I suspect) the way you call the colorbox function.

      It’s best to try and find a solution in http://www.jacklmoore.com/colorbox/faq/ and https://github.com/jackmoore/colorbox/issues

      More specifically, I think your problem has to do with the following issue:
      https://github.com/jackmoore/colorbox/issues/683

      Reply
      • Manuel
        Posted on January 20, 2015 at 20:24 Permalink

        SOLVE !!

        Thanks.

        I’ve used in the ADD page this code:

        $(“a#copertina”).bind(‘click’, function () {
        $(“.inline”).colorbox({
        inline:true,
        href: ‘#inline_content’,
        width:”70%”,
        maxHeight:”90%”
        });
        });

        And in the same page I’ve inserted this link to open the colorbox with the scrollbar plugin:

        <a href="#">Inline HTML</a>

        Great!

        Reply
  13. kumarraj
    Posted on January 20, 2015 at 06:18 Permalink

    How to append the elements to scroll container dynamically is there any plugin methods….

    I want add the elements dynamically on button click…….. Is this plugin provides any method or not

    Reply
    • malihu
      Posted on January 20, 2015 at 08:43 Permalink

      No, you do it normally with js/jquery.

      Just remember that your actual content resides within .mCSB_container element after the scrollbar has initialized. So for example, you can to add/modify content like this (assuming the element with the scrollbar is .content):
      $(".content .mCSB_container").append("html");

      Reply
  14. mediatel
    Posted on January 18, 2015 at 10:39 Permalink

    thanks for this post maliho.

    Reply
  15. Josh R
    Posted on January 16, 2015 at 00:22 Permalink

    Cool plugin! Will it work for textareas, or is it for non-form elements only?

    Reply
  16. Michalis
    Posted on January 15, 2015 at 16:44 Permalink

    Hello, Good script. Is it possible when the mouse move oute of the div, the scroller to move automatically back at the top?

    Reply
    • malihu
      Posted on January 15, 2015 at 17:33 Permalink

      Hello,

      Yes you could do it but I think it might hinder the user-experience(?).
      In any case, you can do something like:
      $(".content").mCustomScrollbar().on("mouseleave",function(){ $(this).mCustomScrollbar("scrollTo","top"); });
      The above chains scrollbar initialization with the mouseleave event.
      You basically need to call plugin’s scrollTo method in your event(s).

      Reply
      • Michalis
        Posted on January 15, 2015 at 18:38 Permalink

        Thanks! I agree with you, autoscrolling is not so good for user experience but my friend want it to work like this at his website.

        Reply
        • malihu
          Posted on January 15, 2015 at 18:54 Permalink

          No problem.
          This was the story of my life when I was working in agencies with “big” clients :)

          Reply
  17. abdessamad idrissi
    Posted on January 14, 2015 at 19:36 Permalink

    Thanks for the great plugin!
    Is it possible to call scroll action from some other element other that mouse scroll or scrollbar draging?
    I have a button and need to scroll when we hove on button and stop when we are not hover.

    Is that possible? Thanks!

    Reply
  18. aclondon
    Posted on January 14, 2015 at 18:36 Permalink

    The image size seems to be fixed for the Light theme. Is it possible to have the images resized to fit a small frame size. I have restricted frame which is only 80px high, we can use setHeight for content but the images are no resized and overflow the content boundaries.

    Thanks in advance.
    AC.

    Reply
    • malihu
      Posted on January 15, 2015 at 00:36 Permalink

      What image? Can you provide more info about the issue?

      Reply
      • aclondon
        Posted on January 15, 2015 at 14:34 Permalink

        Hi there,
        Thanks for the prompt reply.

        I suppose what I am looking for is a way to control the size of the image in the section.

        I have tried using

        but the images still come out at 115x115px on the scroller.

        Hope this makes sense. If this is not possible then I guess I will need to manuall re-size the images.

        Thanks again.
        AC.

        Reply
        • malihu
          Posted on January 15, 2015 at 15:57 Permalink

          I’ll need to see this to be able to help. It sounds more like a general CSS (not plugin related?) issue but I can’t be sure…
          Can you send me (e.g via email) your link or HTML?

          Reply
  19. anonymous
    Posted on January 14, 2015 at 16:32 Permalink

    Hi,

    Thanks for this awesome plugin!

    I was able to use the plugin smoothly and when I use it again in another section of my site, the scroll bar doesn’t move at all. The buttons and dragger are visible but the scroll bar couldn’t be scrolled.

    Any thoughts?

    Much thanks!

    Reply
    • malihu
      Posted on January 14, 2015 at 17:04 Permalink

      Do you get any console errors? Can you send me a link?

      Reply
  20. Drew Peterson
    Posted on January 14, 2015 at 08:45 Permalink

    Help! I had a catastrophic failure on my site, and I’ve been trying to rebuild it. I have one huge problem though, my main content div keeps getting shrunk to 45px height with no scrollbar by this plugin. This is because it creates a div with this class:
    mCSB_container mCS_no_scrollbar

    So, please help! Why does mCS_no_scrollbar show up in the mCSB_container div? I have two other divs it works fine in. I see no difference in the divs…

    Reply
    • malihu
      Posted on January 14, 2015 at 16:06 Permalink

      Does your element have a height (or max-height) value?

      Reply
      • Lili
        Posted on January 20, 2015 at 20:14 Permalink

        Hi! thanks for this helpful plugin!, I think i’m experimenting this same issue, is there any other reason besides height property that can be causing this issue?
        Thanks in advance…

        Reply
        • malihu
          Posted on January 20, 2015 at 20:31 Permalink

          Not really, unless your content is not long enough to require a scrollbar(?)
          If your height value is in percentage, make sure that your element’s parent container also has a (fixed) height value set. If you can send me a link (or code) I’ll be able to help.

          Reply
  21. Jos van Riswick
    Posted on January 13, 2015 at 15:37 Permalink

    http://josvanriswick.a2hosted.com/test1/scrollbartest1.html

    Thnx for giving us this wonderful plugin !

    Is there someone who knows if / how it is possible to get
    the parent element to move when the scrolling in a child
    has reached the end of its scrolling interval. (if you know
    what i mean)

    See example page above: there is a parent scrolling in the
    x direction with children scrolling in the y direction. On a
    mobile device, when I scroll in one of the children (up down)
    the parent is completely locked. Ie if I scroll left-right in the
    children, the page is unresponsive. Desired behaviour: if
    I scroll left / right in the children they reach their end of
    x-scrolling domain and the parent should scroll in the
    x direction. Anyone know how to do this ?

    thnx,

    Jos

    Reply
    • malihu
      Posted on January 13, 2015 at 16:33 Permalink

      Thanks for the feedback!
      Sorry but at the moment there’s no quick or easy solution for this. I’ll try some tests and fix it on the next plugin version.

      Reply
      • Jos van Riswick
        Posted on January 13, 2015 at 16:38 Permalink

        ok thnxxx………

        Reply
  22. Pavel
    Posted on January 13, 2015 at 13:38 Permalink

    Hi,

    when content is scrolled all the way to the bottom ( onTotalScroll) and mouse pointer is still on the element (hover), is it possible to disabled (stop) page scrolling? Page scrolling will be active in a moment when mouse pointer is removed (un-hover) from the element.

    Thank you for your reply

    Pavel

    Reply

Comments pages: 1 57 58 59

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>

css.php