OverlayScrollbars: A JavaScript repository from abuzarmushtaq

OverlayScrollbars

OverlayScrollbars is a javascript scrollbar plugin which hides the native scrollbars and provides custom styleable scrollbars, but keeps the native functionality and feeling.

Why?

I've created this plugin because I hate ugly and space consuming scrollbars. Similar plugins haven't met my requirements in terms of features, quality, simplicity, license or browser support.

Goals & Features

A simple, powerful and good documented API.
High browser compatibility (IE8+, Safari6+, Firefox, Opera, Chrome and Edge).
Usage of the most recent technologies to ensure maximum efficiency and performance on newer browsers.
Can be used without any dependencies or with jQuery.
Automatic update detection - after the initialization you don't have to worry about updating.
Mouse and touch support.
Textarea support.
Direction RTL support. (with normalization)
Simple and effective scrollbar-styling.

Demo & Documentation

You can find a detailed documentation, demos and theme templates here.

Dependencies

The default version doesn't requires any dependencies!

If you are using the jQuery dependent version it obviously requires jQuery to work.
It was tested with the jQuery versions: 1.9.1, 2.x, 3.x, and it won't work with jQuery slim.

Download

manually

Download OverlayScrollbars manually from Releases.

npm

OverlayScrollbars can be also downloaded from npm.

npm install overlayscrollbars

Usage

HTML

Load your CSS file(s) before the JS file(s), to prevent unexpected bugs.

Include OverlayScrollbars.css and OverlayScrollbars.js to your HTML file.

<!-- Plugin CSS -->
<link type="text/css" href="path/to/OverlayScrollbars.css" rel="stylesheet"/>
<!-- Plugin JS -->
<script type="text/javascript" src="path/to/OverlayScrollbars.js"></script>

If you are using the jQuery version include jQuery before the plugin and use jquery.overlayScrollbars.js

<!-- Plugin CSS -->
<link type="text/css" href="path/to/OverlayScrollbars.css" rel="stylesheet"/>
<!-- jQuery JS -->
<script type="text/javascript" src="path/to/jquery.js"></script>
<!-- Plugin JS -->
<script type="text/javascript" src="path/to/jquery.overlayScrollbars.js"></script>

Javascript

Initialize the plugin after your document has been fully loaded.

Default initialization:

$(function() {
	//The first argument are the elements to which the plugin shall be initialized
	//The second argument has to be at least a empty object or a object with your desired options
	OverlayScrollbars(document.querySelectorAll('body'), { });
});

jQuery initialization (will only work with the jQuery version):

$(function() {
	//The passed argument has to be at least a empty object or a object with your desired options
	$('body').overlayScrollbars({ });
});

Options

Due to clarity i can't provide all informations here.
Take the table below only as a overview of all options.
Please read the much more detailed documentation.

option		type	default	description
className		string / null	`"os-theme-dark"`	The class name which shall be added to the host element.
resize		string	`"none"`	The resize behavior of the host element. This option works exactly like the CSS3 resize property.
sizeAutoCapable		boolean	`true`	Indicates whether the host element is capable of "auto" sizes such as: `width: auto` and `height: auto`.
clipAlways		boolean	`true`	Indicates whether the content shall be clipped always.
normalizeRTL		boolean	`true`	Indicates whether RTL scrolling shall be normalized.
paddingAbsolute		boolean	`false`	Indicates whether the padding for the content shall be absolute.
autoUpdate		boolean / null	`null`	Indicates whether the plugin instance shall be updated continuously within a update loop.
autoUpdateInterval		number	`33`	The interval in milliseconds in which a auto update shall be performed for this instance.
nativeScrollbarsOverlaid : {
	showNativeScrollbars	boolean	`false`	Indicates whether the native overlaid scrollbars shall be visible.
	initialize	boolean	`true`	Indicates whether the plugin shall be initialized even if the native scrollbars are overlaid. If you initialize the plugin on the body element, I recommend to set this option to false.
}
overflowBehavior : {
	x	string	`"scroll"`	The overflow behavior for the x (horizontal) axis.
	y	string	`"scroll"`	The overflow behavior for the y (vertical) axis.
}
scrollbars : {
	visibility	string	`"auto"`	The basic visibility of the scrollbars.
	autoHide	string	`"never"`	The possibility to hide visible scrollbars automatically after a certain action.
	autoHideDelay	number	`800`	The delay in milliseconds before the scrollbars gets hidden automatically.
	dragScrolling	boolean	`true`	Defines whether the scrollbar-handle supports drag scrolling.
	clickScrolling	boolean	`false`	Defines whether the scrollbar-track supports click scrolling.
	touchSupport	boolean	`true`	Indicates whether the scrollbar reacts to touch events.
}
textarea : {
	dynWidth	boolean	`false`	Indiactes whether the textarea width will be dynamic (content dependent).
	dynHeight	boolean	`false`	Indiactes whether the textarea height will be dynamic (content dependent).
}
callbacks : {
	onInitialized	function / null	`null`	Gets fired after the plugin was initialized. It takes no arguments.
	onInitializationWithdrawn	function / null	`null`	Gets fired after the initialization of the plugin was aborted due to the option `nativeScrollbarsOverlaid : { initialize : false }`. It takes no arguments.
	onDestroyed	function / null	`null`	Gets fired after the plugin was destryoed. It takes no arguments.
	onScrollStart	function / null	`null`	Gets fired after the user starts scrolling. It takes one argument.
	onScroll	function / null	`null`	Gets fired after every scroll. It takes one argument.
	onScrollStop	function / null	`null`	Gets fired after the user stops scrolling. It takes one argument.
	onOverflowChanged	function / null	`null`	Gets fired after the overflow has changed. It takes one argument.
	onOverflowAmountChanged	function / null	`null`	Gets fired after the overflow amount has changed. It takes one argument.
	onDirectionChanged	function / null	`null`	Gets fired after the direction has changed. It takes one argument.
	onContentSizeChanged	function / null	`null`	Gets fired after the content size has changed. It takes one argument.
	onHostSizeChanged	function / null	`null`	Gets fired after the host size or host padding has changed. It takes one argument.
	onUpdated	function / null	`null`	Gets fired after the host size has changed. It takes one argument.
}

Methods

Click on the method name to open a more detailed documentation.

Instance methods:

name	description
.options()	Returns or sets the options of the instance.
example(s): //get options var options = instance.options(); //set options instance.options({ className : null });
.update()	Updates the instance.
example(s): //soft update instance.update(); //hard update instance.update(true);
.sleep()	Disables every observation of the DOM and puts the instance to "sleep". This behavior can be reset by calling the `update()` method.
example(s): //put the instance to sleep instance.sleep();
.scroll()	Returns the scroll information or sets the scroll position.
example(s): //get scroll information var scrollInfo = instance.scroll(); //scroll 50px on both axis instance.scroll(50); //add 10px to the scroll offset of each axis instance.scroll({ x : "+=10", y : "+=10" }); //scroll to 50% on both axis with a duration of 1000ms instance.scroll({ x : "50%", y : "50%" }, 1000); //scroll to the passed element with a duration of 1000ms instance.scroll($(selector), 1000);
.scrollStop()	Stops the current scroll-animation.
example(s): //scroll-animation duration is 10 seconds instance.scroll({ y : "100%" }, 10000); //abort the 10 seconds scroll-animation immediately instance.scrollStop(); //scroll-animation duration is 1 second instance.scroll({ y : "100%" }, 1000);
.getElements()	Returns all relevant elements.
example(s): //get the element to which the plugin was applied var pluginTarget = instance.getElements().target;
.getState()	Returns a object which describes the current state of this instance.
example(s): //get the state of the plugin instance var pluginState = instance.getState();
.destroy()	Destroys and disposes the current instance and removes all added elements form the DOM.
example(s): //destroy the instance instance.destroy();

Global methods:

name	description
OverlayScrollbars.defaultOptions()	Returns or Sets the default options for each new plugin initialization.
example(s): //get the current defaultOptions var defaultOptions = OverlayScrollbars.defaultOptions(); //set new default options OverlayScrollbars.defaultOptions({ className : "my-custom-class", resize : "both" });
OverlayScrollbars.globals()	Returns a plain object which contains global information about the plugin and each instance of it.
example(s): //get the global information var globals = OverlayScrollbars.globals();

Future Plans

Minimize the code as much as possible.
Frequent updates in terms of bugsfixes and enhancements.

License

MIT

abuzarmushtaq/OverlayScrollbars