Website • Documentation • Demos • Extensions • FAQ
OverlayScrollbars is a javascript scrollbar plugin which hides native scrollbars, provides custom styleable overlay scrollbars and keeps the native functionality and feeling.
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.
- 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.
- Extremely powerful scroll method with features like animations, relative coordinates, scrollIntoView and more.
- Mouse and touch support.
- Textarea and Body support.
- RTL Direction support. (with normalization)
- Simple and effective scrollbar-styling.
- Rich extension system.
- TypeScript support.
OverlayScrollbars provides its own wrapper components for popular component-based front-end frameworks:
npm install overlayscrollbars-react
npm install overlayscrollbars-vue
npm install overlayscrollbars-ngx
|
Thanks to BrowserStack for sponsoring open source projects and letting me test OverlayScrollbars for free. |
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 OverlayScrollbars manually from Releases.
You can use OverlayScrollbars via a cdn.
OverlayScrollbars can be downloaded from npm.
npm install overlayscrollbars
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>
Initialize the plugin after your document has been fully loaded.
Default initialization:
document.addEventListener("DOMContentLoaded", 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:
$(function() {
//The passed argument has to be at least a empty object or a object with your desired options
$('body').overlayScrollbars({ });
});
OverlayScrollbars provides its own TypeScript declarations:
npm install @types/overlayscrollbars
I recommend setting these options in your tsconfig.json:
{
"compilerOptions": {
"allowSyntheticDefaultImports": true,
"esModuleInterop": true
}
}
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. | |
snapHandle | boolean | false |
Indicates whether the scrollbar handle-offset shall be snapped. | |
} | ||||
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). | |
inheritedAttrs | string / array / null | ["style", "class"] |
During initialization: Attributes which the generated host-element shall inherit from from the target textarea-element. During destruction: Attributes which the target textarea-element shall inherit from from the generated host-element. |
|
} | ||||
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. | |
} |
Click on the method name to open a more detailed documentation.
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(); |
|
.ext() | Returns the instance of a certain extension of the current plugin instance. |
example(s)://get the instance of the extension "myExtension"
var extensionInstance = instance.ext("myExtension"); |
|
.addExt() | Adds a extension to the current instance. |
example(s)://add the registered extension "myExtension" to the plugin instance
var extensionInstance = instance.addExt("myExtension"); |
|
.removeExt() | Removes a extension from the current instance. |
example(s)://add the registered extension "myExtension" to the plugin instance
instance.addExt("myExtension");
//remove the added extension "myExtension" from the plugin instance
instance.removeExt("myExtension"); |
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(); |
|
OverlayScrollbars.extension() | Registers, Unregisters or returns extensions. |
example(s)://register a dummy extension with the name "myExtension"
OverlayScrollbars.extension("myExtension", function() { return { }; });
//unregister the extension with the name "myExtension"
OverlayScrollbars.extension("myExtension", null);
//get the extension-object with the name "myExtension"
var registeredExtension = OverlayScrollbars.extension("myExtension");
//get all registered extension-objects
var extensionObjects = OverlayScrollbars.extension(); |
|
OverlayScrollbars.valid() | Checks whether the passed object is a non-destroyed OverlayScrollbars instance. |
example(s)://create OverlayScrollbars instance
var osInstance = OverlayScrollbars(document.body, { });
//returns true
OverlayScrollbars.valid(osInstance);
//destroy the instance
osInstance.destroy();
//returns false
OverlayScrollbars.valid(osInstance);
//returns false
OverlayScrollbars.valid({ }); |
- Minimize the code as much as possible.
- Frequent updates in terms of bug-fixes and enhancements.
MIT