- 
+ 
-
+
-
-
-
-
-[README](https://github.com/KingSora/OverlayScrollbars/tree/master/packages/overlayscrollbars-react)
+## Getting started
+#### npm & Node
+OverlayScrollbars can be downloaded from [npm](https://www.npmjs.com/package/overlayscrollbars) or the package manager of your choice:
```sh
-npm install overlayscrollbars-react
+npm install overlayscrollbars
+```
+After installation it can be imported:
+```js
+import 'overlayscrollbars/overlayscrollbars.css';
+import { OverlayScrollbars } from 'overlayscrollbars';
```
-
+
-
-[README](https://github.com/KingSora/OverlayScrollbars/tree/master/packages/overlayscrollbars-vue)
+You can use OverlayScrollbars without any bundler or package manager.
+Simply download it from the [Releases](https://github.com/KingSora/OverlayScrollbars/releases) or use a [CDN](https://cdnjs.com/libraries/overlayscrollbars).
-```sh
-npm install overlayscrollbars-vue
+- Use the javascript files with the `.browser` extension.
+- If you target old browsers use the `.es5` javascript file, for new browsers `.es6`.
+- For production use the javascript / stylesheet files with the `.min` extension.
+
+Embedd OverlayScrollbars manually in your HTML:
+```html
+
+
+```
+
+
-
-[README](https://github.com/KingSora/OverlayScrollbars/tree/master/packages/overlayscrollbars-ngx)
+> __Note__ For now please refer to the TypeScript definitions for a more detailed description of all possibilities.
-```sh
-npm install overlayscrollbars-ngx
+The only required field is the `target` field. This is the field to which the plugin is applied to.
+If you use the object initialization only with the `target` field, the outcome is equivalent to the element initialization:
+```js
+// Both initializations have the same outcome
+
+OverlayScrollbars(document.querySelector('#myElement'), {});
+OverlayScrollbars({ target: document.querySelector('#myElement') }, {});
+```
+
+In the initialization object you can specify how the library is handling generated elements.
+For example you can appoint an existing element as the `viewport` element. Like this the library won't generate it but take the specified element instead:
+
+ ```js
+OverlayScrollbars({
+ target: document.querySelector('#target'),
+ elements: {
+ viewport: document.querySelector('#viewport'),
+ },
+}, {});
+```
+
+This is very useful if you have a fixed DOM structure and don't want OverlayScrollbars to generate its own elements. Those cases arise very often when you want an other library to work together with OverlayScrollbars.
+
+---
+
+You can also decide to which element the scrollbars should be applied to:
+
+ ```js
+OverlayScrollbars({
+ target: document.querySelector('#target'),
+ scrollbars: {
+ slot: document.querySelector('#target').parentElement,
+ },
+}, {});
+```
+
+---
+
+And last but not least you can decide when the initialization should be canceled:
+ ```js
+OverlayScrollbars({
+ target: document.querySelector('#target'),
+ cancel: {
+ nativeScrollbarsOverlaid: true,
+ body: null,
+ }
+}, {});
+```
+
+In the above example the initialization is canceled when the native scrollbars are overlaid or when your target is a `body` element and the plugin determined that a initialization to the `body` element would affect native functionality like `window.scrollTo`.
+
+| 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. | -|
| updateOnLoad | -string / array / null | -["img"] |
- Selectors of which the elements load event shall be handled by the plugin. Thats means OverlayScrollbars will trigger a automatic update if a element with a matching selector emits a load event. Per default OverlayScrollbars will update automatically if a img element loads. |
- |
| 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 |
- Indicates whether the textarea width will be dynamic (content dependent). | -
| - | dynHeight | -boolean | -false |
- Indicates 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. | -
| } | -||||
| 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({ });
- |
- |