jQuery custom content scroller

• Plugin home
• Changelog
• Code examples and tutorials

Frequently Asked Questions

• How do I remove scrolling animation?

  Set scrollInertia option parameter to 0 (zero)

  $(selector).mCustomScrollbar({
      scrollInertia: 0
  });
  

• Is there a way to detect how a scroll event was triggered?

  There's an object generated by the script which lets you know how scrolling events where last triggered. The object returns "internal" (default) for events triggered by plugin script or "external" for events triggered by other scripts (e.g. via the scrollTo method).
  You can access the object like this: object.data("mCS").trigger
  Example:

  if($(selector).data("mCS").trigger==="external"){
      //last scrolling event was triggered by scrollTo method
  }else{
      //last scrolling event was triggered by the user
  }
  

• How to stop page scrolling completely when hovering over the element with the custom scrollbar?

  You can use mouseWheel:preventDefault option parameter:

  $(selector).mCustomScrollbar({
      mouseWheel:{ preventDefault: true }
  });
  

  This will affect mouse-wheel scrolling. There's no option for touch, as depending on the device, page layout and zoom level, it can easily render the page/rest of the content unusable.

• When updating content via ajax, I get an error and/or scrollbar disappears!

  To update the content on elements that already have custom scrollbar(s), you need to add/append the new content inside the .mCSB_container element (instead directly to the element you called mCustomScrollbar function).
  Example:

  //scrollbar initialization 
  $(".content").mCustomScrollbar();
  
  //at some point later on (within another script, function, ajax call etc.)
  $(".content .mCSB_container").append("
  new content...
  ");
  //or targeting a specific .mCSB_container element (usefull with nested scrollbars)
  $("#mCSB_1_container").append("
  new content...
  ");
  

• How to resize or change up/down button images?

  This is done via CSS. You can edit directly jquery.mCustomScrollbar.css or overwrite the rules in your own stylesheet. The buttons classes are mCSB_buttonUp and mCSB_buttonDown. By default, the arrow images are set using CSS image sprites, meaning that all themes arrows are contained in a single file: mCSB_buttons.png.

  To change the dimensions of the buttons, you need to adjust few additional CSS rules to compensate for the new buttons sizes. Below is an example of changing the size of buttons to 26x26 pixels (from the default 16x20 pixels) with a custom image for each one.

• Can I make the scrollbar appear over the content (without margins)?

  There are multiple ways of doing this. You can use specific theme(s) (e.g. "minimal"), option parameters like scrollbarPosition and/or edit the CSS rules directly. For more info see author's reply to a similar question in comments.

• How to set a fixed size (height/width) for the scrollbar dragger?

  You can have a fixed size scrollbar that doesn't change its dimensions according to content length by following these steps:

  1. Set autoDraggerLength option to false
  2. Set your desired scrollbar height on line 106 of jquery.mCustomScrollbar.css, or in your own stylesheet using the "mCSB_dragger" class:
     .mCSB_scrollTools .mCSB_dragger{ height: 30px; }
     For horizontal scrollbars, set its width on line 177 of jquery.mCustomScrollbar.css, or in your CSS:
     .mCSB_scrollTools.mCSB_scrollTools_horizontal .mCSB_dragger{ width: 30px; }

• How do I add scrollbar(s) on dynamic elements that are not in the DOM (yet)?

  You can use the live option parameter and call mCustomScrollbar function normally without having to wait for the dynamic elements to be available in the DOM.
  Example:

  $(selector).mCustomScrollbar({
  	live: "on"
  });
  

  You can also use: live: "once" to disable the live option event after the first invocation.

  To disable the live option at any point set live option to "off":

  $(selector).mCustomScrollbar({
  	live: "off"
  });
  

  An alternative way to live is the liveSelector option parameter which you can define the matching set of elements (instead of the current selector) to add scrollbar(s) when available:

  $(selector).mCustomScrollbar({
  	liveSelector: ".my-future-class"
  });
  

• Can I have both vertical and horizontal scrollbars on the whole page (e.g. on body tag)?

  Yes but for the horizontal scrollbar you'll need a couple of special CSS rules. See this comment for code examples.

• Horizontal scrollbar doesn't seem to work!? 🙁

  Normally, if your content works with browser's default horizontal scrollbar, it should also work with the custom one. If you've already set axis: "x" (to enable horizontal scrollbar), there's a good chance you also need to set autoExpandHorizontalScroll option parameter to true. For example:

  $(selector).mCustomScrollbar({
  	axis: "x",
  	advanced:{ autoExpandHorizontalScroll: true }
  });
  

• Is it possible to disable mouse-wheel on-the-fly (after initialization)?

  Yes. See this thread on github. You can do $(selector).data("mCS").opt.mouseWheel.scrollAmount=0; to disable it and $(selector).data("mCS").opt.mouseWheel.scrollAmount="auto"; to (re)enable it.

• How to make the scrollbar start from the bottom?

  There are more than one ways available to start scrolling from the bottom at initialization:

  1. Chaining scrollTo method

  $(selector).mCustomScrollbar({
      //your options...
  }).mCustomScrollbar("scrollTo","bottom",{scrollInertia:0});
  

  2. Using setTop option

  $(selector).mCustomScrollbar({
      setTop:"-999999px"
  });
  

• How to make the vertical scrollbar appear to the left of the content?

  If you're developing a right-to-left (RTL) text web page, the scrollbar will switch to the left side automatically (assuming you're using either HTML dir="rtl" or CSS direction: rtl). To set the scrollbar on the left manually, you need to change or overwrite the rules in lines 65 and 54 of jquery.mCustomScrollbar.css.

  For example, adding the following to your CSS will overwrite the above rules and set the default vertical scrollbar on the left of content:

  /* reset/remove right position so scrollbar appears on left */
  .mCustomScrollbar .mCSB_scrollTools{ 
    right: auto;
  }
  
  /* switch margin from right to left */
  .mCustomScrollbar .mCSB_inside > .mCSB_container{ 
    margin-right: 0;
    margin-left: 30px;
  }
  

• How to switch between native and custom scrollbar according to viewport width?

  You can do this by checking the viewport width and initializing or destroying the custom scrollbar accordingly. The condition to check viewport width should match CSS media queries and triggered on page load and browser resize. There are two ways you can do this:

  1. Using Window.matchMedia() (IE10+)

  (function($){
      $(window).on("load resize",function(){
          if(window.matchMedia("(min-width: 640px)").matches){
              $("#your-element-id").mCustomScrollbar({ /* scrollbar options */ });
          }else{
              $("#your-element-id").mCustomScrollbar("destroy");
          }
      });
  })(jQuery);
  

  2. Checking a CSS rule that the media query changes (should always work)

  Assuming your element is #content-1:

  /* CSS */ 
  #content-1:after{ display: none; content: "custom-scrollbar"; }
  @media screen and (max-width: 640px){
      #content-1:after{ content: ""; }
  }
  

  /* JS */
  (function($){
      $(window).on("load resize",function(){
          var selector="#content-1", //your element(s) selector
              cssFlag=window.getComputedStyle(document.querySelector(selector),":after").getPropertyValue("content").replace(/"/g,'');
          if(cssFlag){
              $(selector).mCustomScrollbar({ /* scrollbar options */ });
          }else{
              $(selector).mCustomScrollbar("destroy");
          }
      });
  })(jQuery);
  

• Can I have a scrollable table with fixed header?

  Yes but you’ll need extra markup to separate thead from tbody and fixed-width (in pixels, percentage etc.) table cells. This is the best way to have a table with fixed header with or without a custom scrollbar.

  I've created a working example at http://manos.malihu.gr/repository/custom-scrollbar/demo/examples/table-fixed-header-test.html which uses 2 separate tables (one for header and one for body) and 2 extra divs (one body wrapper and one overall wrapper).