![OverlayScrollbars](https://kingsora.github.io/OverlayScrollbars/img/logo.png) ## 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. - 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](https://kingsora.github.io/OverlayScrollbars). ## Dependencies **Currently this library requires [jQuery](https://jquery.com/) to work.** The plugin was tested with the jQuery versions: 1.9.1, 2.x, 3.x. It doesn't work with jQuery slim. ## Usage #### HTML Include [jQuery](https://jquery.com/) and **OverlayScrollbars** to your HTML file. Load your CSS file(s) before the JS file(s), to prevent unexpected bugs. ```html ``` #### Javascript Initialize the plugin after your document has been fully loaded on the desired element. ```js $(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](https://kingsora.github.io/OverlayScrollbars/#!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 after a certain action.
autoHideDelay number 800 The possibility to hide visible scrollbars after a certain action.
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
window.overlayScrollbarsDefaultOptions() Returns or Sets the default options for each new plugin initialization.
example(s):
//get the current defaultOptions
var defaultOptions = window.overlayScrollbarsDefaultOptions();
//set new default options
window.overlayScrollbarsDefaultOptions({
	className : "my-custom-class",
	resize    : "both"
});
window.overlayScrollbarsGlobals() Returns a plain object which contains global information about the plugin and each instance of it.
example(s):
//get the global information
var globals = window.overlayScrollbarsGlobals();
## Future Plans - Minimize the code as much as possible. - If desired by the community I'll write and provide a jQuery independent version of the plugin. - Frequent updates in terms of bugsfixes and enhancements. ## License MIT