Mobile-friendly Custom Scrollbar Plugin With jQuery - NiceScroll

Mobile-friendly Custom Scrollbar Plugin With jQuery - NiceScroll
File Size: 129 KB
Views Total:
Last Update:
Publish Date:
Official Website: Go to website
License: MIT
   

NiceScroll is an easy yet robust jQuery plugin that allows to append pretty nice, touch-enabled and highly customizable scrollbar to any scrollable area such as browser window, DIV container, iframe, textarea and much more. Supports both desktop and mobile devices. Additionally, the plugin comes with a zoom feature which enables the user to enlarge the scrollable area in the full size screen. Smooth scroll is supported as well.

How to use it:

1. Download, include the jQuery NiceScroll plugin's script after jQuery library and we're ready to go.

<script src="//code.jquery.com/jquery.min.js"></script>
<script src="js/jquery.nicescroll.min.js"></script>

2. The JavaScript to replace the default browser scrollbar with default options.

// The document page (body)
$("html").niceScroll();  

3. The JavaScript to replace the default scrollbar of a specific scrollable container.

$("#selector").niceScroll({
  // options here
}); 

4. All default options which can be used to customize the scrollbar.

$("#selector").niceScroll({

  // z-index
  zindex: "auto",

  // opacity when cursor is inactive
  cursoropacitymin: 0,

  // opacity when cursor is active
  cursoropacitymax: 1,

  // cursor color
  cursorcolor: "#424242",

  // cursor width
  cursorwidth: "6px",

  // cursor border properties
  cursorborder: "1px solid #fff",
  cursorborderradius: "5px",

  // animation speed of smooth scroll
  scrollspeed: 60,

  // scrolling speed with mouse wheel
  mousescrollstep: 8 * 3,

  // enable touch behavior
  touchbehavior: false,

  // use hardware accelerated scroll if supported
  hwacceleration: true,

  // use CSS transitions if supported
  usetransition: true,

  // enable zoom feature
  boxzoom: false,

  // double click to zoom
  dblclickzoom: true,

  // zoom via gestures
  gesturezoom: true,

  // displays "grab" icon
  grabcursorenabled: true,

  // true: hide when no scrolling
  // "cursor":only cursor hidden
  // false:do not hide,
  // "leave":hide only if pointer leaves content
  // "hidden":hide always
  // "scroll":how only on scroll       
  autohidemode: true,

  // background
  background: "",

  // auto resize iframe
  iframeautoresize: true,

  // min height of cursor
  cursorminheight: 32,

  // preserve native scroll behavior
  preservenativescrolling: true,

  // offset top/left for rail position
  railoffset: false,
  railhoffset: false,

  // enable scroll bouncing at the end of content as mobile-like
  bouncescroll: true,

  // enable page down scrolling when space bar has pressed
  spacebarenabled: true,

  // padding for rail bar
  railpadding: {
    top: 0,
    right: 0,
    left: 0,
    bottom: 0
  },

  // disable outline
  disableoutline: true,

  // enable horizontal scrolling
  horizrailenabled: true,

  // alignment of rail bar
  railalign: "right",
  railvalign: "bottom",

  // enable 3D transforms
  enabletranslate3d: true,

  // enable mouse wheel
  enablemousewheel: true,

  // enable keyboard
  enablekeyboard: true,

  // enable smooth scroll
  smoothscroll: true,

  // click on rail make a scroll
  sensitiverail: true,

  // enable mouse caption lock API
  enablemouselockapi: true,

  // fixed height of cursor
  cursorfixedheight: false,

  // dead zone in pixels for direction lock activation
  directionlockdeadzone: 6,

  // set the delay in microseconds to fading out scrollbars
  hidecursordelay: 400,

  // detect bottom of content and let parent to scroll, as native scroll does
  nativeparentscrolling: true,

  // enable auto-scrolling of content when selection text
  enablescrollonselection: true,

  // overlow
  overflowx: true,
  overflowy: true,

  // drag speed
  cursordragspeed: 0.3,

  // RTL mode
  rtlmode: "auto",

  // drag cursor in touch / touchbehavior mode
  cursordragontouch: false,

  // it permits horizontal scrolling with mousewheel on horizontal only content, 
  // if false (vertical-only) mousewheel don't scroll horizontally, if value is auto detects two-axis mouse
  oneaxismousemode: "auto",

  // define custom path for boxmode icons
  scriptpath: getScriptPath(),

  // prevent scrolling on multitouch events
  preventmultitouchscrolling: true,

  // force MutationObserver disabled
  disablemutationobserver:false

}); 

5. API methods.

// Get nicescroll object
$("#selector").getNiceScroll();

// Hide scrollbar
$("#selector").getNiceScroll().hide();

// Check for scrollbars resize
$("#selector").getNiceScroll().resize();

// Scroll to a position:
$("#selector").getNiceScroll(0).doScrollLeft(x, duration); // Scroll X Axis
$("#selector").getNiceScroll(0).doScrollTop(y, duration); // Scroll Y Axis

Change log:

v3.7.6 (2017-07-20)

  • Fixed: Error in remove() using angular nicescroll with modal popup

v3.7.4 (2017-07-14)

  • Fixed: Calling .remove() throws an error after update to v. 3.7.4
  • Fixed: more robust hybrid system support mouse + touch events aka no drag and scroll
  • Fixed: scroll is not working on edge and firefox browsers in touchscreen laptops
  • Fixed: typos on navigator.maxTouchPoints
  • Removed outdated self.visibility

v3.7.4 (2017-07-03)

  1. Fixed: touchpad scrolling support for MS Surface aka FYI - Browser test results on Surface Pro touchscreen and touchpad
  2. Fixed: changed scrollbarid setting procedure because uglify mades uncompatible code for IE8 aka use nicescroll in IE8
  3. Fixed: preserve scrol chain
  4. Fixed: page scrollbar not customized on android
  5. Fixed: prevent bar flickering when window not changed aka Using this plugin I got a flickering scroll bar
  6. Changed: more responsive direct scrolling from bars
  7. Changed: more consistence scrolling speed on many browsers (Chrome, Firefox, Edge)
  8. Changed: minor code optimizations and jshint check
  9. Changed: jQuery "bind" event function changed to "on", migration to jQuery 3 (still jQuery 1 compatible)
  10. Changed: Using jQuery.expr.pseudos, migration to jQuery 3 (still jQuery 1 compatible)
  11. Changed: changed arguments for doScrollBy and doScrollLeftBy

v3.7.3 (2017-06-19)

  • onscrollstart error on emulatetouch
  • a little size optimization for uglufy version

2017-05-22

  • mobile android/ios fixes and other important fixes

This awesome jQuery plugin is developed by inuyaksa. For more Advanced Usages, please check the demo page or visit the official website.