# jQuery Scrollbar

Cross-browser CSS customizable scrollbar with advanced features:

- Easy to implement
- No fixed height or width needed
- Supports responsive design
- Customizable CSS
- Standard browser scroll behaviour
- Supports vertical and horizontal scrollbars or both
- Automatically re-initializes scrollbars
- Supports external scrollbars
- Provides a AngularJS directive
- Supports the use as textarea scrollbar
- Browser support: IE7+, Edge, Firefox, Opera, Chrome, Safari

#### Basic Scrollbars Demo

#### Advanced Scrollbars Demo

#### jQuery Scrollbars as AngularJS directive

#### Download example

### Easy to implement

Go to the demo pages, find a scrollbar that fits your needs, copy the HTML/CSS/JavaScript and paste it to your page. Modify CSS styles to change scrollbar colors/sizes. If you can't find a scrollbar that fits your needs, contact the author and your scrollbar will be added to the demo page.

### No fixed height or width needed

Most of the scrollbar plugins require container height or width to be set in order to calculate scrollbar sizes. jQuery Scrollbar does not require height, nor width. You can use max-height/max-width to restrict container sizes, or use standard height/width in pixels/percents in the parent container.

### Supports responsive design

jQuery Scrollbar can be used in responsive designs as there is no need to set fixed height/width to the container. Scrollbars will be automatically updated/hidden/displayed when content or container size changes.

### Customizable CSS

Use CSS to customize scrollbar colors, sizes or positions. Use simple or advanced HTML structure to customize how scrollbars should look. If simple or advanced HTML structure is not what you are looking for, you can use your own HTML structure with custom elements.

### Standard browser scroll behaviour

If your browser can scroll content, jQuery Scrollbar will scroll it too! Why? Because it does not emulate browser scroll behaviour as many plugins do, instead hides standard scrollbars and displays custom ones. You want to scroll with mouse middle button? – Just use it! You want to scroll with touch? – Do it! Your browser supports custom scroll behavior? – Use it too! Use the standard or jQuery scrollTop/scrollLeft functions to get current scroll offset or scroll to any position. Use the standard "scroll" event to handle content scrolling. You don't need to know custom functions/events – everything is done based on standard scroll behaviour.

### Supports vertical and horizontal scrollbars or both

Most of the scrollbar plugins allow using either vertical or horizontal scrollbars. Only a few can use both vertical and horizontal scrollbars and they are using scroll emulation which has limitations. jQuery Scrollbar does not emulate scroll behaviour. Also it can work with both vertical and horizontal scrollbars together.

### Automatically re-initializes scrollbars

Usually scrollbar size and positions are calculated when plugin is initialized. What if content or container size is changed with javascript/ajax? - You have to update plugin to recalculate scrollbar sizes. And it's OK because you know when content is changed. But what to do if you don't know when it is changed? For example, if content contains images without height/width. These images change content size after loading. There are 3 obvious ways: always set image height/width (and force users to set image size for content added with WYSIWYG editor), wait for whole page to load and then initialize scrollbars or handle content images loading and then re-initialize scrollbar plugin. Annoying, isn't it?

jQuery Scrollbar handles content/container size changes and recalculate scrollbar sizes automatically. Just initialize it once and forget about it.

### Supports external scrollbars

jQuery Scrollbar supports 3 types of scrollbars: inner — scrollbar is displayed over content (Apple Mac OS); outer — scrollbar shifts content to display itself (Microsoft Windows scrollbars); external — scrollbar is located in any place of your page. So, you can choose between Apple Mac and Windows style scrollbar or even place it outside of the container and style it as you wish. Cool, isn't it?

### Provides a AngularJS directive

Now you can easily use jQuery Scrollbar with AngularJS as directive. Just include module jQueryScrollbar as dependency in your module, and you can use jQuery Scrollbar on your container with attribute data-jquery-scrollbar. jQuery Scrollbar as AngularJS directive.

### Textarea scrollbars

Apply jQuery Scrollbar to your textarea and enjoy CSS styled scrollbars. Supports IE8+. Fixed height/width are required.

### Browser support: IE7+, Edge, Firefox, Opera, Chrome, Safari

Of course all modern browsers are supported starting from IE7. The most problematic browser is IE, as you already suspect. But it's not IE7, it's IE8! Surprised? I was! IE7 works better with height/width calculations than IE8. IE8 renderer is crashed when using max-height with overflow:auto. It is officially logged as a bug in the final version of IE8 with no fix. There are also other bugs with max-height/max-width and positioning. So, be careful if you are going to support IE8.

#### Advanced features that standard scroll has, but scroll emulation plugins have to emulate or don't have at all

- mouse middle button / touch / arrow buttons scrolling
- auto content scrolling when selecting text
- auto scrolling to focused element

## jQuery Scrollbar Options

- autoScrollSize [true|false] (default: true)
  automatically calculate scrollbar size depending on container/content size
- autoUpdate [true|false] (default: true)
  automatically update scrollbar if container/content size is changed
- disableBodyScroll [true|false] (default: false)
  if this option is enabled and the mouse is over the scrollable container, the main page won't be scrolled
- duration [ms] (default: 200)
  scroll speed duration when the mouse is over scrollbar (scroll emulating mode)
- ignoreMobile [true|false] (default: false)
  do not initialize custom scrollbars on mobile devices
- ignoreOverlay [true|false] (default: false)
  do not initialize custom scrollbars in browsers when native scrollbars overlay content (Mac OS, mobile devices, etc...)
- scrollStep [px] (default: 30)
  scroll step when the mouse is over the scrollbar (scroll emulating mode)
- showArrows [true|false] (default: false)
  add a class to show scrollbar arrows in the advanced scrollbar
- stepScrolling [true|false] (default: true)
  emulate step scrolling on mousedown over scrollbar
- scrollx [string|element] (default: simple)
  simple, advanced, HTML or jQuery element for horizontal scrollbar
- scrolly [string|element] (default: simple)
  simple, advanced, HTML or jQuery element for vertical scrollbar
- onDestroy [function] (default: null)
  callback function when scrollbar is destroyed
- onInit [function] (default: null)
  callback function when scrollbar is initialized at the first time
- onScroll [function] (default: null)
  callback function when container is scrolled
- onUpdate [function] (default: null)
  callback function before scrollbars size is calculated

## Limitations

- scrollable elements should not have paddings, margins, left/top values
- do not use max-height in IE8 – it crashes browser renderer
- custom scroll is not initialized in Firefox under MacOS because of a bug while hiding native overlay scrollbar
- custom scroll works incorrectly if containers children's height is set in percent of parent (issue #57)

## FAQ

1. Question: I need padding between border/scrollbar and text, but scrollbar does not allow it. What should I do?

   Answer: Wrap the inner content in the div with padding

2. Question: I need space between content with scrollbar and the rest of the page. What should I do?

   Answer: Wrap the scrollable content into container with padding.

3. Question: If content contains images, content size can be changed after images will be loaded. Should I re-initialize scrollbar?

   Answer: No, scrollbar detects content/container size changes automatically and recalculates its size or hides/shows scrollbars.

4. Question: How can I scroll content to a custom position?

   Answer: Use standard jQuery scrollTop/scrollLeft functions on the container. For example if you have a container with a class "scrollbar-macosx" use the following code to scroll 50px from top:

       jQuery('.scrollbar-macosx').scrollTop(50);

5. Question: I want to know when the content is scrolled. Is there any callback for this?

   Answer: Yes, you can use "onScroll" callback (look at AngularJS example), or use the standard "scroll" event on the container. For example you have a container with a class "scrollbar-macosx", then use the following code to handle the scroll event:

       jQuery('.scrollbar-macosx').not('.scroll-wrapper').on("scroll", function(){
           console.log('content is scrolling');
       });

6. Question: The scrollbar does not replace the standard scrollbar. What should I do?

   Answer: It's not a good idea to replace the standard scrollbar for a whole page. But if you really need it, wrap all page into container with height/width 100%, overflow: auto and apply the scrollbar to this container.

7. Question: I don't want to see horizontal scrollbar ever. What should I do?

   Answer: Hide it with CSS like this:

       .scroll-element.scroll-x {
           display: none !important;
       }

   But don't forget that even if the scrollbar is hidden, the content still may be scrollable horizontally.

8. Question: Using jQuery's .width() or .height() on a container will return incorrect values. What is going on?

   Answer: Inner scrollable content uses additional height/width & offset of the scrollbar to hide it. To get correct height/width values use the visible container:

       jQuery('.scrollbar-macosx').not('.scroll-content').height();
       jQuery('.scrollbar-macosx').not('.scroll-content').width();

9. Question: How to detect when a DIV is scrolled to the bottom edge?

   Answer: You can make calculations using jQuery's "scroll" event or you can use the "onScroll" callback function that provides information about container's sizes & offset:

       jQuery('.scrollbar-dynamic').scrollbar({
           "onScroll": function(y, x){
               if(y.scroll == y.maxScroll){
                   console.log('Scrolled to bottom');
               }
           }
       });

10. Question: Can I use jQuery Scrollbar to customize textarea scrollbar?

    Answer: Yes, you can. Textarea scrollbars are supported now. Look at Basic Scrollbars Demo page.

11. Question: Is it possible to set scrollbars max/min size?

    Answer: Use CSS max-height/min-height (max-width/min-width) to set scrollbar size limits.

12. Question: I have a question / want to report an issue. How can I contact the author?

    Answer: Please send an email to 13real008@gmail.com

##### Compare with other popular scrollbars