Scrollbars

1. Scrollbars

  • Trying different scrollbar plugins, I wasn't able to find a lightweight and easy to use one, which is also touch friendly.
    So I thought it's better to make one.
    It's minimal but should be enough for most cases.
    You can also use other more advanced plugins if necessary. There should be no conflicts.
  • Here is a simple snippet which add vertical scrollbars to an element and limits its size to 400:
     $('#my-content').ace_scroll({size: 400});
    

2. Options

  • size which is 200px by default
     $('#my-content').ace_scroll({size: 400});
    
    You can also specify size using data-size attribute:
    ...
  • horizontal default=false. If true, horizontal scrollbars will be added
    $('#my-content').ace_scroll({horizontal: true});
    
  • mouseWheel default=true. Scrolls content on mouse wheel event. When end of content is reached, mouse wheel event will be propagated to window
  • mouseWheelLock default=false. If true and we have reached end of scrolling on our element, mouse wheel event won't be propagated to window
    lockAnyway default=false. If true, even if scrollbars are not needed and are not visible yet, mouse wheel event won't be propagated to window
     $('#my-content').ace_scroll({size: 300, mouseWheelLock: true});
    
  • styleClass additional style classes you can add to scrollbars. See next section for more info.
  • hoverReset default=true, because of window size changes and other document layout changes, content sizes may change and we may need to reset scrollbar size.
    It can be done on mouseenter event, which is set to true by default.
  • reset default=false. If true, content will be scrolled to 0, on initialization.
    Does not work when the element is hidden at first.
  • dragEvent default=false. If true an event will be triggered when user starts dragging scrollbars using mouse.
  • scrollEvent default=false. If true an event will be triggered when content is scrolled.
  • touchDrag default=true, which adds touch drag event for touch devices.
  • hideOnIdle will hide scrollbars when user is not scrolling content
    You may also want to use hideDelay which specifies time before hiding scrollbars and also observeContent which specifies whether content and scrollbar size should be reset before making it visible:
     $('#my-content').ace_scroll({
        //other options
        hideOnIdle: true,
        hideDelay: 1500,
        observeContent: true
    });
    

3. Styles

  • Some additional classes you can add using styleClass option:
    1. scroll-margin which add 1px space between content and scrollbars
    2. scroll-left shows scrollbars on left instead of right
    3. scroll-top shows horizontal scrollbars on top instead of bottom
    4. scroll-dark darker scrollbars
    5. scroll-light lighter scrollbars
    6. no-track hides scroll track
    7. scroll-visible scrollbars always visible
    8. scroll-thin thinner scrollbars
    9. scroll-chrome similar to latest version of Google Chrome scrollbars
  •  $('#my-content').ace_scroll({
        size: 300,
        styleClass: 'scroll-dark scroll-left scroll-thin'
     });
    

4. Events

  • If you set scrollEvent to true, a scroll event will be triggered when element is scrolled:
     $('#my-content')
     .ace_scroll({
        scrollEvent: true
     })
     .on('scroll', function() {
        //element scrolled
     });
    
    But it's better to listen to the inner content's native scroll event:
     $('#my-content').find('.scroll-content').on('scroll', function() {
        //element scrolled
     });
    
  • If you set dragEvent to true, some drag events will be triggered when scrollbars are dragged:
     $('#my-content')
     .ace_scroll({
        dragEvents: true
     })
     .on('drag.start', function() {
        //started dragging
     })
     .on('drag._end', function() {
        //ended dragging
     })
    

5. Touch Drag Event

  • There is also a custom touch drag event specifically for use on scrollbars.
    You can use it with other elements as well, though I recommend a more advanced library such as Hammer.js
  • You can use it like this:
    $('#some-element').on('ace_drag', function(event) {
      //var dir = event.direction;// up down left right
      //var distanceX = event.dx 
      //var distanceY = event.dy
    })
    

6. Functions

  • The following functions are available for scroller plugin:
    1. reset resets scrollbar size
    2. disable disables scrollbars
    3. enable enables scrollbars
    4. end scroll to end
    5. start scroll to start
    6. update updates an option (currently only size, style and mousewheel options)
  • $('#my-content').ace_scroll('reset');
    $('#my-content').ace_scroll('disable');
    
    $('#my-content').ace_scroll('update', {size: 250});
    $('#my-content').ace_scroll('modify', completely_new_options);
    

7. Horizontal

  • Horizontal scrollbars can be created by specifying horizontal option:
    $('#my-content').ace_scroll({
        horizontal: true,
        size: 600,
        styleClass: 'scroll-top',
        mouseWheelLock: true
    });
    
  • Sometimes you may need to add some padding to the element if scrollbars appear above content:
    $('#my-content').ace_scroll({
        horizontal: true,
        //options here
    }).css('padding-top', 15);
    
  • If you are using RTL (right to left) direction, please note that horizontal scrolling is inconsistent between browsers.
    So it's better to change scrollbars to LTR and make the content RTL again.
    You can use .make-ltr and .make-rtl classes:
     $('#my-content').addClass('make-ltr')
     .find('.scroll-content').wrapInner('<div class="make-rtl" />');
    
  • Or statically inside your HTML:
     
    ...
    $('#my-content').ace_scroll({
        horizontal: true,
        //other options here
    })
    

8. Sidebar Scrollbars

  • You can also use scrollbar for sidebar whether it's fixed or not.
  • I have used two approaches for sidebar
  • The first one which is used by default, does not use overflow:hidden and can be used only on fixed sidebar.
    The advantage is that .hover submenus or mininized sidebar can also have scrollbars and submenus will be shown outside of sidebar area without problem.
  • Second one uses real scrollbars and has overflow:hidden applied to it.
    It can be used on both normal and fixed sidebar.
    To enable it you should build a custom JS using 2nd sidebar scrollbar style.
  • Each one has several options which you can edit inside:
    1. assets/js/ace/ace.js
    2. assets/js/ace.js
    3. dist/js/ace.min.js

    Look for sidebar_scrollable and change options as needed.
  • Options for first style (fixed sidebar only):
    1. scroll_to_active If true, sidebar will be scrolled down to show active menu item on page load
    2. include_shortcuts If true, shortcuts will also be inside scroll area. Otherwise it will be above scroll area
    3. include_toggle If true, sidebar toggle(minimize button) will also be inside scroll area. Otherwise it will be below scroll area
    4. smooth_scroll If true, sidebar scrolling will be smooth using CSS3 transition
    5. outside If true, scrollbar will be outside of scroll area
  • Options for secod style (normal/fixed sidebar):
    1. only_fixed If true, scrollbars will be enabled for fixed sidebar only
    2. scroll_to_active If true, sidebar will be scrolled down to show active menu item on page load
    3. include_shortcuts If true, shortcuts will also be inside scroll area. Otherwise it will be above scroll area
    4. include_toggle If true, sidebar toggle(minimize button) will also be inside scroll area. Otherwise it will be below scroll area