Custom scrollbars for modern webapps. Supercharge the native scroll!

Optiscroll

Optiscroll is an tiny (9kB min / 3.9kB gzip) and highly optimized custom scrollbar library for modern web apps.

Optiscroll aims to be as light as possible in order to not affect the performance of your webapp. Optiscroll does not replace the scrolling logic with Javascript. It only hides native scrollbars and allows you to style the fake scrollbars as you like. Moreover, Optiscroll adds custom events and methods to extend browser scroll functionalities.

Features

• Lightweight and without dependencies
• Highly optimized
• Vertical and horizontal scrollbars support
• Both ltr and rtl text direction support (with smart detection)
• Nested scrollbars support
• Custom events
• Animated scrollTo and scrollIntoView
• Auto update on content/scroll area change
• Integrated page bounce fix for iOS
• Optional jQuery plugin

Browser support

Optiscroll works in all modern browsers (IE11 and above). Keep in mind that if Optiscroll does not work your web page will still fallback to default scrollbars.

How to use Optiscroll

Installation

Grab optiscroll.min.js (or jquery.optiscroll.min.js) from dist folder or:

bower install optiscroll --save
# or
npm install optiscroll --save

Basic usage

Include Optiscroll library and stylesheet

<link rel="stylesheet" href="optiscroll.css">
<!-- include the plain JS version -->
<script src="optiscroll.js"></script>
<!-- OR include the jQuery plugin -->
<script src="jquery.optiscroll.js"></script>

Optiscroll automatically wraps your content with a scrollable element, but if you need more control you can create your own element and set wrapContent: false.

<div id="scroll" class="optiscroll">
    <!-- scrollable area, an additional wrapper will be created -->
    My content
</div>

Initialize it in your JS code

// plain JS version
var element = document.querySelector('#scroll')
var myOptiscrollInstance = new Optiscroll(element);

// jQuery plugin
$('#scroll').optiscroll()

Instance options

Examples:

// change min and max track size - plain JS version
var myOptiscrollInstance = new Optiscroll(element, { maxTrackSize: 50, minTrackSize: 20 });

// Force scrollbars on touch devices - jQuery plugin
$('#scroll').optiscroll({ forceScrollbars: true });

Instance methods

scrollTo ( destX, destY [, duration] )

Scroll to a specific point with a nice animation. If you need to scroll a single axis then set the opposite axis destination to false. By default the duration is calculated based on the distance (eg: 500px in 700ms, 1000px in 1080ms, 2000px in 1670ms, ...). Alternatively you can set your fixed duration in milliseconds.

Examples:

// scroll vertically by 500px (scroll duration will be auto) - plain JS version
myOptiscrollInstance.scrollTo(false, 500);

/* The jQuery plugin allows you to call a method in two ways */

// scroll horizontally to right in 100ms
$('#scroll').data('optiscroll').scrollTo('right', false, 100);

// scroll horizontally by 500px and vertically to bottom with 'auto' duration
$('#scroll').optiscroll('scrollTo', 500, 'bottom', 'auto');

scrollIntoView (elem [, duration, delta])

Scrolls the element into view. The alignment will be driven by the nearest edge. By default the duration is calculated based on the distance (eg: 500px in 700ms, 1000px in 1080ms, 2000px in 1670ms, ...). delta is the optional distance in px from the edge. Per edge distances can be defined.

Examples:

// scrolls element with id anchor-1 into view (scroll duration will be auto) - plain JS version
myOptiscrollInstance.scrollIntoView('#anchor-1');

/* The jQuery plugin allows you to call a method in two ways */

// scrolls jQuery element into view in 500ms and with a distance from the edges of 20px
var $el = $('.my-element').last();
$('#scroll').data('optiscroll').scrollIntoView($el, 500, 20);

// scrolls jQuery element into view with a custom bottom and right distance
$('#scroll').optiscroll('scrollIntoView', $el, 'auto', { bottom: 20, right: 30 });

update ()

Optiscroll caches some DOM properties (like scrollHeight, clientHeight, ...) in order to avoid quering the DOM (and trigger a layout) each time the user scrolls. Usually the update method is called by an internal timer (see the checkFrequency global option). So you should not care about it. However if you have disabled the auto update feature for an instance (via the autoUpdate option) or globally (via the checkFrequency option), you have to call the update method in your code.

destroy ()

If you want to remove Optiscroll, this method will clean up the class names, unbind all events and remove the scrollbar elements. Anyway, Optiscroll is clever enough to destroy itself automatically if its element is removed from the DOM (so it avoids memory leaks).

myOptiscrollInstance.destroy();

/* The jQuery plugin should be destroyed this way 
 * so it handles removing its internal reference properly */

$('#scroll').optiscroll('destroy');

Instance events

Each instance will fire a set of custom events after user interaction. Each event will include a detail property with some useful data about the scrolled element.

Detail object attributes

Examples:

// plain JS listener
document.querySelector('#scroll').addEventListener('scrollreachtop', function (ev) {
    console.log(ev.type) // outputs 'scrollreachtop'
    console.log(ev.detail.scrollTop) // outputs scroll distance from top
    console.log(ev.detail.scrollbarV.percent) // outputs vertical scrolled %
});

// jQuery listener
$('#scroll').on('scrollstop', function (ev) {
    console.log(ev.type) // outputs 'scrollstop'
    console.log(ev.detail.scrollBottom) // outputs scroll distance from bottom
    console.log(ev.detail.scrollbarH.percent) // outputs horizontal scrolled %
});

Global options

Examples:

// set the scrollbar update interval to 30 FPS
Optiscroll.globalSettings.scrollMinUpdateInterval = 1000 / 30;
// disable auto update for all Optiscroll instances
Optiscroll.globalSettings.checkFrequency = 0;

SCSS styling options

If you want more control over the styling, you can set these SCSS variables before including scss/optiscroll.scss in your .scss file:

$optiscroll-namespace: 'optiscroll'; // custom css class namespace
$optiscroll-classPrefix: $optiscroll-namespace + '-'; // same as js classPrefix option

$optiscroll-forceScrollbarV: false; // css trick to force vertical scrollbars
$optiscroll-forceScrollbarH: false; // css trick to force horizontal scrollbars
$optiscroll-supportRtl: true; // enable/disable rules for rtl support
$optiscroll-defaultStyle: true; // enable/disable default styling

Known limitations

• forceScrollbars is not 100% reliable on iOS Safari (due to on-the-fly style changes), it is ignored on Firefox Mac w/ trackpad (see FF bug) and on older versions of Chrome/Safari this setting will hide scrollbars also on child scrollable elements.

• On iOS/Android, custom events (and scrollbars if forceScrollbars: true) are fired/updated whenever browser fires the scroll event.

Why still timers to check size/content changes?

Even if there are clever tricks to detect an element size change (eg iframes) there is still no reliable way to detect overflow changes (the event is Firefox only and Chrome has deprecated it). So, timers are still the most performing solution because they allow a more fine grained control.

Running Tests

Optiscroll is designed to run in the browser so the tests explicitly require a browser environment instead of any JavaScript environment (i.e. node.js). You can simply load test/index.html in any browser to run all the tests.

Upgrading

From v2 to v3

No changes should be required, just dropped IE < 11 support and added bunch of new features.

From v1 to v2

• classPrefix option no longer adds - to the namespace, so it allows you to pick your favourite separator (or no separator at all) for .optiscroll* elements.
• Optiscroll now automatically wraps inner content. So, remove .optiscroll-content from your html (behaviour customisable on v3).
• Styles organisation got a major overhaul, so my suggestion is to go and have a look.

History & Changelog

Check Github Releases page

License

This program is free software; it is distributed under an MIT License.

Copyright (c) 2017 Alberto Gasparin Initially developed at Wilson Fletcher design studio (Contributors).