OverlayScrollbars

https://kingsora.github.io/OverlayScrollbars/
Admin
A JavaScript scrollbar plugin that hides native scrollbars and provides custom styleable overlay...
Tokens:13,535
Snippets:141
Trust Score:9.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### Consuming Plugins Example

Source: https://kingsora.github.io/OverlayScrollbars

Demonstrates how to import and use OverlayScrollbars plugins in your project using JavaScript or TypeScript.

```APIDOC
## Consuming Plugins

### Description
Plugins are consumed by importing them from the 'overlayscrollbars' package and then calling the `plugin` method on the `OverlayScrollbars` static object.

### Usage
```javascript
import { OverlayScrollbars, ScrollbarsHidingPlugin, SizeObserverPlugin, ClickScrollPlugin } from 'overlayscrollbars';

// Single plugin
OverlayScrollbars.plugin(ScrollbarsHidingPlugin);

// Multiple plugins
OverlayScrollbars.plugin([SizeObserverPlugin, ClickScrollPlugin]);
```
```

--------------------------------

### Install OverlayScrollbars via npm

Source: https://kingsora.github.io/OverlayScrollbars

Install the OverlayScrollbars package using npm. This is the recommended method for projects using a package manager.

```bash
npm install overlayscrollbars
```

--------------------------------

### Custom Scrollbar Theme Example

Source: https://kingsora.github.io/OverlayScrollbars

Demonstrates how to create a custom theme by setting specific CSS Custom Properties for horizontal and vertical scrollbars.

```css
// Horizontal and vertical scrollbar are 10px 
.os-theme-custom {
  --os-size: 10px;
}
 
// Horizontal scrollbar is 10px
.os-theme-custom.os-scrollbar-horizontal {
  --os-size: 10px;
}
// Vertical scrollbar is 20px
.os-theme-custom.os-scrollbar-vertical {
  --os-size: 20px;
}
```

--------------------------------

### Consuming OverlayScrollbars Plugins

Source: https://kingsora.github.io/OverlayScrollbars

Demonstrates how to import and use OverlayScrollbars plugins. Shows examples for adding a single plugin and multiple plugins using the `plugin` method.

```javascript
import { 
  OverlayScrollbars, 
  ScrollbarsHidingPlugin, 
  SizeObserverPlugin, 
  ClickScrollPlugin 
} from 'overlayscrollbars';

// Single plugin
OverlayScrollbars.plugin(ScrollbarsHidingPlugin);

// Multiple plugins
OverlayScrollbars.plugin([SizeObserverPlugin, ClickScrollPlugin]);
```

--------------------------------

### Instance Plugin Module Example

Source: https://kingsora.github.io/OverlayScrollbars

Defines an instance plugin module named 'examplePlugin'. The instance function is invoked for each OverlayScrollbars instance and can register event listeners.

```javascript
const instancePlugin = {
  // Plugin has the name `examplePlugin`.
  examplePlugin: {
    // Instance function describes na instance module and returns the module instance or void / undefined if no instance is needed.
    // The `osInstance` parameter is the OverlayScrollbar instance the plugin is bound to.
    // The `event` parameter is a function which adds events to the instance which can't be removed from outside the plugin.
    // The `osStatic` parameter is the global `OverlayScrollbar` object.
    instance: (osInstance, event, osStatic) => {
      let count = 0;
 
      const instancePluginModuleInstance = {
        getCount: () => count,
        increment: () => { count++ },
      }
 
      // Event which fires when the instance was initialized.
      event('initialized', () => {
        console.log("instance initialized");
      });
 
      // Event which fires when the viewport was scrolled.
      const removeScrollEvent = event('scroll', () => {
        console.log("viewport scrolled");
        removeScrollEvent(); // Removes the event after the first scroll.
      });
      
      return instancePluginModuleInstance;
    }
  }
}
```

--------------------------------

### Import OverlayScrollbars and Plugins

Source: https://kingsora.github.io/OverlayScrollbars

Import the necessary CSS and JavaScript components for OverlayScrollbars and its plugins. Ensure the CSS path is correct for your setup.

```javascript
import 'overlayscrollbars/overlayscrollbars.css';
import { 
  OverlayScrollbars, 
  ScrollbarsHidingPlugin, 
  SizeObserverPlugin, 
  ClickScrollPlugin 
} from 'overlayscrollbars';
```

--------------------------------

### Static Plugin Module Example

Source: https://kingsora.github.io/OverlayScrollbars

Defines a static plugin module named 'examplePlugin'. The static function is invoked when the plugin is added and can return an instance with methods and properties.

```javascript
const staticPlugin = {
  // Plugin has the name `examplePlugin`.
  examplePlugin: {
    // The `static` function describes a static module and returns the module instance or void / undefined if no instance is needed.
    // The `osStatic` parameter is the global `OverlayScrollbars` object.
    static: (osStatic) => {
      let count = 0;
      const staticPluginModuleInstance = {
        getCount: () => count,
        increment: () => { count++ },
      }
      return staticPluginModuleInstance;
    }
  }
}
```

--------------------------------

### Initialize OverlayScrollbars on an Element

Source: https://kingsora.github.io/OverlayScrollbars

Initialize a new OverlayScrollbars instance on a specific HTML element. This example shows a simple initialization with an empty options object.

```javascript
// Simple initialization with an element
const osInstance = OverlayScrollbars(document.querySelector('#myElement'), {});
```

--------------------------------

### Instance Methods

Source: https://kingsora.github.io/OverlayScrollbars

The OverlayScrollbars instance provides methods to interact with and manage the scrollbars after initialization. These include methods for getting and setting options, and for managing event listeners.

```APIDOC
## Instance Methods

### `options(): Options`
Get the current options of the instance.
returns| description  
---|---  
`Options`| The current options.

### `options(newOptions, pure?): Options`
Sets the current options of the instance.
parameter| type| description  
---|---|---  
newOptions| `PartialOptions`| The new (partial) options which should be applied.
pure| `boolean | undefined`| Whether the options should be reset before the new options are added.
returns| description  
---|---  
`Options`| The complete new options.

### `on(eventListeners, pure?): Function`
Adds event listeners to the instance.
parameter| type| description  
---|---|---  
eventListeners| `EventListeners`| An object which contains the added listeners. The fields are the event names and the listeners.
pure| `boolean | undefined`| Whether all already added event listeners should be removed before the new listeners are added.
returns| description  
---|---  
`Function`| A function which removes all added event listeners.

### `on(name, listener): Function`
Adds a single event listener to the instance.
parameter| type| description  
---|---|---  
name| `string`| The event name.
listener| `Function`| The function invoked when the event is dispatched.
returns| description  
---|---  
`Function`| A function which removes the added event listener.
```

--------------------------------

### Get Current OverlayScrollbars Options

Source: https://kingsora.github.io/OverlayScrollbars

Retrieve the current configuration options of an existing OverlayScrollbars instance. This method returns the complete options object.

```javascript
osInstance.options();
```

--------------------------------

### state()

Source: https://kingsora.github.io/OverlayScrollbars

Gets the instance's state. This method returns an object that describes the current state of the scrollbar instance.

```APIDOC
## state()

### Description
Gets the instance's state.

### Method
`state`

### Returns
- **State** - An object describing the state of the instance.
```

--------------------------------

### OverlayScrollbars.nonce()

Source: https://kingsora.github.io/OverlayScrollbars

Sets or gets the nonce attribute for inline styles, which can be used for Content Security Policy (CSP) compliance.

```APIDOC
## OverlayScrollbars.nonce()

### Description
Sets or gets the nonce attribute for inline styles, which can be used for Content Security Policy (CSP) compliance.

### Method
POST

### Endpoint
/nonce

### Parameters
#### Query Parameters
- **newNonce** (string | undefined) - Optional - The new nonce attribute to set. If undefined, the current nonce is returned.

### Response
#### Success Response (200)
- **nonce** (string | undefined) - The current nonce attribute if set, or undefined if not set.

#### Response Example
```json
{
  "nonce": "your-nonce-value"
}
```
```

--------------------------------

### elements()

Source: https://kingsora.github.io/OverlayScrollbars

Gets the instances elements. This method returns an object containing references to the elements managed by the scrollbar instance.

```APIDOC
## elements()

### Description
Gets the instances elements.

### Method
`elements`

### Returns
- **Elements** - An object describing the elements of the instance.
```

--------------------------------

### plugin(plugin)

Source: https://kingsora.github.io/OverlayScrollbars

Gets the instance's plugin module instance. This method allows retrieval of a specific plugin's instance associated with the scrollbar.

```APIDOC
## plugin(plugin)

### Description
Gets the instance modules instance of the passed plugin.

### Method
`plugin`

### Parameters
#### Path Parameters
- **plugin** (`object`) - Required - The plugin to get the instance for.

### Returns
- **object | undefined** - An object which describes the plugins instance modules instance or `undefined` if no instance was found.
```

--------------------------------

### OverlayScrollbars.trustedTypePolicy()

Source: https://kingsora.github.io/OverlayScrollbars

Sets or gets the Trusted Type policy for enhanced security against DOM-based cross-site scripting (XSS) attacks.

```APIDOC
## OverlayScrollbars.trustedTypePolicy()

### Description
Sets or gets the Trusted Type policy for enhanced security against DOM-based cross-site scripting (XSS) attacks.

### Method
POST

### Endpoint
/trustedTypePolicy

### Parameters
#### Query Parameters
- **newTrustedTypePolicy** (TrustedTypePolicy | undefined) - Optional - The new Trusted Type policy to set. If undefined, the current policy is returned.

### Response
#### Success Response (200)
- **policy** (TrustedTypePolicy | undefined) - The current Trusted Type policy if set, or undefined if not set.

#### Response Example
```json
{
  "policy": "yourTrustedTypePolicy"
}
```
```

--------------------------------

### Get and Set Scroll Position

Source: https://kingsora.github.io/OverlayScrollbars

Use this snippet to retrieve the current scroll offsets or to set a new scroll position for the viewport element. Ensure you have an OverlayScrollbars instance and access its elements.

```javascript
const { viewport } = osInstance.elements();
const { scrollLeft, scrollTop } = viewport; // Get scroll offset
viewport.scrollTo({ top: 0 }); // Set scroll offset
```

--------------------------------

### Registering a Plugin with OverlayScrollbars

Source: https://kingsora.github.io/OverlayScrollbars

Demonstrates how to register a plugin with the OverlayScrollbars static object. Ensure the plugin is imported before use.

```javascript
OverlayScrollbars.plugin(SomePlugin);
```

--------------------------------

### Basic Object Initialization

Source: https://kingsora.github.io/OverlayScrollbars

This is an equivalent to element initialization when using the object syntax with only the `target` field. The `target` field is the only required field.

```javascript
// Both initializations have the same outcome
 
OverlayScrollbars(document.querySelector('#myElement'), {});
OverlayScrollbars({ target: document.querySelector('#myElement') }, {});
```

--------------------------------

### Invoking Instance Plugin Module

Source: https://kingsora.github.io/OverlayScrollbars

Demonstrates adding an instance plugin and accessing its instance module. The instance module is invoked for new OverlayScrollbars instances created after the plugin is added.

```javascript
OverlayScrollbars.plugin(instancePlugin); // Plugin is added
 
const osInstance = OverlayScrollbars(document.body, {}); // Plugin's instance module is invoked
const instancePluginInstance = osInstance.plugin(instancePlugin);
 
instancePluginInstance.count; // 0
instancePluginInstance.increment();
instancePluginInstance.count; // 1
```

--------------------------------

### Initialize OverlayScrollbars with Options

Source: https://kingsora.github.io/OverlayScrollbars

Initializes OverlayScrollbars on an element with specific overflow options. Ensure the target element exists and has the ID 'myElement'.

```javascript
OverlayScrollbars(document.querySelector('#myElement'), {
  overflow: {
    x: 'hidden',
  },
});
```

--------------------------------

### OverlayScrollbars.env()

Source: https://kingsora.github.io/OverlayScrollbars

Retrieves information about the current environment in which OverlayScrollbars is running.

```APIDOC
## OverlayScrollbars.env()

### Description
Retrieves information about the current environment in which OverlayScrollbars is running.

### Method
GET

### Endpoint
/env

### Response
#### Success Response (200)
- **Environment** (object) - An object containing environment details.
  - **version** (string) - The current version of OverlayScrollbars.
  - **environment** (string) - The detected environment (e.g., 'browser', 'node').
  - **os** (string) - The detected operating system.
  - **browser** (string) - The detected browser name and version.

#### Response Example
```json
{
  "version": "1.10.0",
  "environment": "browser",
  "os": "Windows 10",
  "browser": "Chrome 91.0.4472.124"
}
```
```

--------------------------------

### Add Multiple Plugins

Source: https://kingsora.github.io/OverlayScrollbars

Adds multiple plugins to OverlayScrollbars simultaneously. This allows for efficient loading of several extensions at once.

```APIDOC
## `plugin(plugins): (object | void)[]`

### Description
Adds multiple plugins to OverlayScrollbars.

### Parameters
#### Path Parameters
- **plugins** (object[]) - Required - The plugins to be added.

### Returns
- **(object | void)[]** - An array describing the plugins static modules instances or `undefined` if no instance was found.
```

--------------------------------

### Invoking Static Plugin Module Instance

Source: https://kingsora.github.io/OverlayScrollbars

Demonstrates how to add a static plugin and access its returned instance. The static module is invoked upon calling OverlayScrollbars.plugin.

```javascript
const staticModuleInstance = OverlayScrollbars.plugin(staticPlugin); // Plugins static module is invoked
staticModuleInstance.count; // 0
staticModuleInstance.increment();
staticModuleInstance.count; // 1
```

--------------------------------

### Initialize OverlayScrollbars with Event Listener

Source: https://kingsora.github.io/OverlayScrollbars

Initialize OverlayScrollbars on an element and provide an initial event listener for the 'updated' event. The listener receives the instance and update arguments.

```javascript
OverlayScrollbars(document.querySelector('#myElement'), {}, {
  updated(osInstance, onUpdatedArgs) {
    // ...
  }
});
```

--------------------------------

### Applying a Custom Scrollbar Theme with JavaScript

Source: https://kingsora.github.io/OverlayScrollbars

Shows how to apply a custom scrollbar theme ('os-theme-custom') to an element using the OverlayScrollbars JavaScript API.

```javascript
OverlayScrollbars(document.body, {
  scrollbars: {
    theme: 'os-theme-custom'
  }
});
```

--------------------------------

### sleep(sleeping)

Source: https://kingsora.github.io/OverlayScrollbars

Puts the instance to sleep or wakes it up. When the instance is sleeping, updates and most event listeners are ignored.

```APIDOC
## sleep(sleeping)

### Description
Puts the instance to sleep or wakes it up.

### Method
`sleep`

### Parameters
#### Path Parameters
- **sleeping** (`boolean`) - Required - Whether the instance should be put to sleep.

### Returns
- **void**
```

--------------------------------

### Object Initialization with Custom Viewport Element

Source: https://kingsora.github.io/OverlayScrollbars

Specify an existing element as the `viewport` element to prevent OverlayScrollbars from generating it. This is useful when integrating with other libraries or when a fixed DOM structure is required.

```javascript
OverlayScrollbars({
 target: document.querySelector('#target'),
 elements: {
   viewport: document.querySelector('#viewport'),
 },
}, {});
```

--------------------------------

### OverlayScrollbars.plugin()

Source: https://kingsora.github.io/OverlayScrollbars

Registers a plugin with OverlayScrollbars. This allows you to extend the functionality of the scrollbar instances.

```APIDOC
## OverlayScrollbars.plugin()

### Description
Registers a plugin with OverlayScrollbars. This allows you to extend the functionality of the scrollbar instances.

### Method
POST

### Endpoint
/plugin

### Parameters
#### Query Parameters
- **SomePlugin** (Plugin) - Required - The plugin to register.

### Request Example
```json
{
  "plugin": "SomePlugin"
}
```

### Response
#### Success Response (200)
- **Success** (boolean) - Indicates if the plugin was registered successfully.

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### scrollbars.pointers

Source: https://kingsora.github.io/OverlayScrollbars

Specifies the pointer types the plugin should react to, such as 'mouse', 'touch', and 'pen'.

```APIDOC
## scrollbars.pointers

### Description
The `PointerTypes` the plugin should react to.

### Parameters
#### Path Parameters
- **pointers** (string[]) - Optional - An array of pointer types.

### Default Value
`['mouse', 'touch', 'pen']`
```

--------------------------------

### Object Initialization with Initialization Cancellation

Source: https://kingsora.github.io/OverlayScrollbars

Configure conditions under which the initialization should be canceled. This includes checking if native scrollbars are overlaid or if initializing on the `body` element would interfere with native functionality.

```javascript
OverlayScrollbars({
 target: document.querySelector('#target'),
 cancel: {
   nativeScrollbarsOverlaid: true,
   body: null,
 }
}, {});
```

--------------------------------

### Scrollbar Click Scroll Behavior Options Interface

Source: https://kingsora.github.io/OverlayScrollbars

Specifies configuration options for click-to-scroll behavior, including distance, duration, and delays.

```typescript
interface ScrollbarsClickScrollBehaviorOptions {
  // The scroll distance of the click scroll. If `0` the `clickScrollDistance` is the destination distance. Default: `one viewport unit`.
  clickScrollDistance: number;
  // The duration in milliseconds it takes to scroll the `clickScrollDistance`. Default `200`.
  clickScrollDuration: number;
  // The delay in milliseconds between click and press scroll. Default: `150`.
  clickPressDelay: number;
  // The duration in milliseconds it takes to travel one viewport unit during press scroll. Default: `90`.
  pressDistanceDuration: number;
}
```

--------------------------------

### Prevent Initialization Flickering with Attribute

Source: https://kingsora.github.io/OverlayScrollbars

Apply the `data-overlayscrollbars-initialize` attribute to the target element and the `html` element when initializing for the `body` to prevent flickering during OverlayScrollbars initialization.

```html
<!-- for the body element -->
<html data-overlayscrollbars-initialize>
  <head></head>
  <body data-overlayscrollbars-initialize></body>
</html>
 
<!-- for all other elements -->
<div data-overlayscrollbars-initialize>
  OverlayScrollbars is applied to this div
</div>
```

--------------------------------

### OverlayScrollbars TypeScript Interfaces

Source: https://kingsora.github.io/OverlayScrollbars

Provides the TypeScript interfaces for the OverlayScrollbars static object, including methods for initialization, validation, environment checks, nonce setting, and plugin management. Also includes the Environment interface detailing scrollbar properties and default settings.

```typescript
interface OverlayScrollbarsStatic {
  (target: InitializationTarget): OverlayScrollbars | undefined;
  (target: InitializationTarget, options: PartialOptions, eventListeners?: EventListeners): OverlayScrollbars;

  valid(osInstance: any): osInstance is OverlayScrollbars;

  env(): Environment;

  nonce(newNonce: string | undefined): void;

  plugin(plugin: Plugin): InferStaticPluginModuleInstance<Plugin>
  plugin(plugins: Plugin[]): InferStaticPluginModuleInstance<Plugin>[];
}

interface Environment {
  scrollbarsSize: XY<number>;
  scrollbarsOverlaid: XY<boolean>;
  scrollbarsHiding: boolean;
  scrollTimeline: boolean;
  staticDefaultInitialization: Initialization;
  staticDefaultOptions: Options;

  getDefaultInitialization(): Initialization;
  getDefaultOptions(): Options;

  setDefaultInitialization(newDefaultInitialization: PartialInitialization): Initialization;
  setDefaultOptions(newDefaultOptions: PartialOptions): Options;
}
```

--------------------------------

### Default OverlayScrollbars Options

Source: https://kingsora.github.io/OverlayScrollbars

The default configuration object for OverlayScrollbars, defining various settings for scrollbar behavior and appearance.

```javascript
const defaultOptions = {
  paddingAbsolute: false,
  showNativeOverlaidScrollbars: false,
  update: {
    elementEvents: [['img', 'load']],
    debounce: {
      mutation: [0, 33],
      resize: null,
      event: [33, 99],
      env: [222, 666, true],
    },
    attributes: null,
    ignoreMutation: null,
    flowDirectionStyles: null,
  },
  overflow: {
    x: 'scroll',
    y: 'scroll',
  },
  scrollbars: {
    theme: 'os-theme-dark',
    visibility: 'auto',
    autoHide: 'never',
    autoHideDelay: 1300,
    autoHideSuspend: false,
    dragScroll: true,
    clickScroll: false,
    pointers: ['mouse', 'touch', 'pen'],
  },
};
```

--------------------------------

### update.debounce.env

Source: https://kingsora.github.io/OverlayScrollbars

Debounce updates triggered by environmental changes like zooming and window resizing. Supports timeout, maxWait, and leading edge invocation.

```APIDOC
## update.debounce.env

### Description
Debounce updates which were triggered by environmental changes. (e.g. zooming & window resize)

### Parameters
#### Query Parameters
- **timeout** (number) - Optional - The debounce timeout in milliseconds.
- **maxWait** (number) - Optional - The maximum time to wait before invoking the function.
- **leading** (boolean) - Optional - Specify invoking on the leading edge of the timeout.

### Default Value
`[222, 666, true]`
```

--------------------------------

### update.debounce.resize

Source: https://kingsora.github.io/OverlayScrollbars

Debounce updates triggered by a ResizeObserver. Allows specifying timeout, maxWait, and leading behavior, or a simple number for timeout.

```APIDOC
## update.debounce.resize

### Description
Debounce updates which were triggered by a ResizeObserver.

### Parameters
#### Query Parameters
- **timeout** (number) - Optional - The debounce timeout in milliseconds.
- **maxWait** (number) - Optional - The maximum time to wait before invoking the function.
- **leading** (boolean) - Optional - Specify invoking on the leading edge of the timeout.

### Default Value
`null`
```

--------------------------------

### Embed OverlayScrollbars Manually via HTML

Source: https://kingsora.github.io/OverlayScrollbars

Include OverlayScrollbars in your HTML manually using script and link tags. Use the `.browser.es.js` file for modern browsers or `.browser.es5.js` for older ones. Use `.min` versions for production.

```html
<link type="text/css" href="path/to/overlayscrollbars.css" rel="stylesheet" />
<script type="text/javascript" src="path/to/overlayscrollbars.browser.es.js" defer></script>
```

--------------------------------

### Add Multiple Event Listeners to OverlayScrollbars Instance

Source: https://kingsora.github.io/OverlayScrollbars

Attach multiple event listeners to an OverlayScrollbars instance by providing an object where keys are event names and values are listener functions. Optionally clear existing listeners before adding new ones.

```javascript
osInstance.on(eventListeners, pure);
```

--------------------------------

### update(force?)

Source: https://kingsora.github.io/OverlayScrollbars

Updates the instance. This method can be used to refresh the scrollbars, optionally forcing a cache invalidation.

```APIDOC
## update(force?)

### Description
Updates the instance.

### Method
`update`

### Parameters
#### Path Parameters
- **force** (`boolean | undefined`) - Optional - Whether the update should force the cache to be invalidated.

### Returns
- **boolean** - A boolean which indicates whether the `update` event was triggered through this update.
```

--------------------------------

### Object Initialization with Custom Scrollbar Slot

Source: https://kingsora.github.io/OverlayScrollbars

Decide to which element the scrollbars should be applied to by specifying the `slot` within the `scrollbars` object. This allows for more control over the DOM structure.

```javascript
OverlayScrollbars({
 target: document.querySelector('#target'),
 scrollbars: {
   slot: document.querySelector('#target').parentElement,
 },
}, {});
```

--------------------------------

### Access OverlayScrollbars API via Global Variable

Source: https://kingsora.github.io/OverlayScrollbars

Access the OverlayScrollbars API using the global `OverlayScrollbarsGlobal` object when embedding manually. This is an alternative to module imports.

```javascript
var { 
  OverlayScrollbars, 
  ScrollbarsHidingPlugin, 
  SizeObserverPlugin, 
  ClickScrollPlugin  
} = OverlayScrollbarsGlobal;
```

--------------------------------

### scrollbars.theme

Source: https://kingsora.github.io/OverlayScrollbars

Applies a specified theme (classname) to the scrollbars.

```APIDOC
## scrollbars.theme

### Description
Applies the specified theme (classname) to the scrollbars.

### Parameters
#### Path Parameters
- **theme** (string) - Optional - The classname of the theme to apply.

### Default Value
`'os-theme-dark'`
```

--------------------------------

### Set OverlayScrollbars Options

Source: https://kingsora.github.io/OverlayScrollbars

Update the configuration options of an OverlayScrollbars instance. You can apply partial options, and optionally reset existing options before applying new ones.

```javascript
osInstance.options(newOptions, pure);
```

--------------------------------

### scrollbars.clickScroll

Source: https://kingsora.github.io/OverlayScrollbars

Enables clicking on the scrollbar track for scrolling. Can be a boolean, 'instant', or a function to customize behavior. Requires ClickScrollPlugin if not false or 'instant'.

```APIDOC
## scrollbars.clickScroll

### Description
Indicates whether you can click on the scrollbar track for scrolling. Can also be a function which customizes the click scroll behavior.

### Parameters
#### Path Parameters
- **clickScroll** (boolean | 'instant' | function) - Required - Configuration for click scrolling.

### Default Value
`false`

### Note
The **ClickScrollPlugin** is required if this option is not `false` or `'instant'`.
```

--------------------------------

### on(name, listeners)

Source: https://kingsora.github.io/OverlayScrollbars

Adds multiple event listeners to the instance. This method allows you to attach several callback functions to specific events dispatched by the scrollbar instance.

```APIDOC
## on(name, listeners)

### Description
Adds multiple event listeners to the instance.

### Method
`on`

### Parameters
#### Path Parameters
- **name** (`string`) - Required - The event name.
- **listeners** (`Function[]`) - Required - The functions invoked when the event is dispatched.

### Returns
- **Function** - A function which removes the added event listeners.
```

--------------------------------

### OverlayScrollbars Options Type

Source: https://kingsora.github.io/OverlayScrollbars

Defines the structure for all configuration options of an OverlayScrollbars instance. Use this to customize scrollbar behavior, appearance, and update triggers.

```typescript
type Options = {
  paddingAbsolute: boolean;
  showNativeOverlaidScrollbars: boolean;
  update: {
    elementEvents: Array<[elementSelector: string, eventNames: string]> | null;
    debounce: {
      mutation: OptionsDebounceValue;
      resize: OptionsDebounceValue;
      event: OptionsDebounceValue;
      env: OptionsDebounceValue;
    };
    attributes: string[] | null;
    ignoreMutation: ((mutation: MutationRecord) => boolean) | null;
    flowDirectionStyles:
      | ((viewport: HTMLElement) => Record<string, unknown>)
      | null;
  };
  overflow: {
    x: OverflowBehavior;
    y: OverflowBehavior;
  };
  scrollbars: {
    theme: string | null;
    visibility: ScrollbarsVisibilityBehavior;
    autoHide: ScrollbarsAutoHideBehavior;
    autoHideDelay: number;
    autoHideSuspend: boolean;
    dragScroll: boolean;
    clickScroll: ScrollbarsClickScrollBehavior;
    pointers: string[] | null;
  };
};
```

--------------------------------

### scrollbars.autoHideDelay

Source: https://kingsora.github.io/OverlayScrollbars

Sets the delay in milliseconds before scrollbars are automatically hidden.

```APIDOC
## scrollbars.autoHideDelay

### Description
The delay in milliseconds before the scrollbars are automatically hidden.

### Parameters
#### Path Parameters
- **autoHideDelay** (number) - Required - The delay in milliseconds.

### Default Value
`1300`
```

--------------------------------

### Viewport Overflow Styling

Source: https://kingsora.github.io/OverlayScrollbars

Use these properties to ensure correct overflow styles for the viewport, especially when other libraries might interfere.

```css
[data-overlayscrollbars-viewport] {
  overflow-x: var(--os-viewport-overflow-x);
  overflow-y: var(--os-viewport-overflow-y);
}
```

--------------------------------

### OverlayScrollbars.valid()

Source: https://kingsora.github.io/OverlayScrollbars

Checks if a given value is a valid and active OverlayScrollbars instance.

```APIDOC
## OverlayScrollbars.valid()

### Description
Checks if a given value is a valid and active OverlayScrollbars instance.

### Method
GET

### Endpoint
/valid

### Parameters
#### Query Parameters
- **osInstance** (any) - Required - The value to check.

### Response
#### Success Response (200)
- **isValid** (boolean) - True if the instance is valid, false otherwise.

#### Response Example
```json
{
  "isValid": true
}
```
```

--------------------------------

### update.flowDirectionStyles

Source: https://kingsora.github.io/OverlayScrollbars

A function that returns styles influencing viewport flow direction, or null for default behavior. Useful for skipping or customizing flow direction checks.

```APIDOC
## update.flowDirectionStyles

### Description
A function which returns a map of styles which influence the viewports flow direction or `null` if the default behavior shall be used.

### Parameters
#### Path Parameters
- **viewport** (function) - Optional - A function that returns a map of styles influencing flow direction.

### Default Value
`null`

### Note
The default behavior reads the computed `display`, `flexDirection`, `direction` and `writingMode` styles of the viewport element. This function can be used to skip or customize the expensive "non default flow direction" check: Use an empty style object to skip the check. Non-empty style objects will lead to a check when they change compared to the previously returned value. Examples of styles which influence the flow direction: `direction: rtl`, `flexDirection: column-reverse`, `writingMode: vertical-rl`.
```

--------------------------------

### OverlayScrollbars TypeScript Interface

Source: https://kingsora.github.io/OverlayScrollbars

Defines the structure and methods for an OverlayScrollbars instance, including options, event handling, updates, state, elements, and plugin management.

```typescript
// A simplified version of the OverlayScrollbars TypeScript interface.
interface OverlayScrollbars {
  // Get the current options of the instance.
  options(): Options;
  // Sets the current options of the instance.
  options(newOptions: PartialOptions, pure?: boolean): Options;
 
  // Adds event listeners to the instance.
  on(eventListeners: EventListeners, pure?: boolean): () => void;
  // Adds a single event listener to the instance.
  on<N extends keyof EventListenerArgs>(name: N, listener: EventListener<N>): () => void;
  // Adds multiple event listeners to the instance.
  on<N extends keyof EventListenerArgs>(name: N, listener: EventListener<N>[]): () => void;
 
  // Removes a single event listener from the instance.
  off<N extends keyof EventListenerArgs>(name: N, listener: EventListener<N>): void;
  // Removes multiple event listeners from the instance.
  off<N extends keyof EventListenerArgs>(name: N, listener: EventListener<N>[]): void;
 
  // Updates the instance.
  update(force?: boolean): boolean;
 
  // Puts the instance to sleep or wakes it up.
  sleep(sleeping: boolean): void;
 
  // Gets the instance's state.
  state(): State;
 
  // Gets the instance's elements.
  elements(): Elements;
 
  // Destroys the instance and removes all added elements.
  destroy(): void;
 
  // Gets the instance modules instance of the passed plugin.
  plugin<P extends InstancePlugin>(osPlugin: P): InferInstancePluginModuleInstance<P> | undefined;
}
 
// Describes a OverlayScrollbars instances state.
interface State {
  // Describes the current padding in pixels.
  padding: TRBL;
  // Whether the current padding is absolute.
  paddingAbsolute: boolean;
  // The client width (x) & height (y) of the viewport in pixels.
  overflowEdge: XY<number>;
  // The overflow amount in pixels.
  overflowAmount: XY<number>;
  // The css overflow style of the viewport.
  overflowStyle: XY<OverflowStyle>;
  // Whether the viewport has an overflow.
  hasOverflow: XY<boolean>;
  // The scroll coordinates of the viewport.
  scrollCoordinates: {
    // The start (origin) scroll coordinates for each axis.
    start: XY<number>;
    // The end scroll coordinates for each axis.
    end: XY<number>;
  };
  // Whether the direction is considered rtl.
  directionRTL: boolean;
  // Whether the instance is sleeping.
  sleeping: boolean;
  // Whether the instance is considered destroyed.
  destroyed: boolean;
}
 
// Describes the elements of a OverlayScrollbars instance.
interface Elements {
  // The element the instance was applied to.
  target: HTMLElement;
  // The host element. It's the root of all other elements.
  host: HTMLElement;
  /**
   * The element responsible for the correct padding.
   * Depending on initialization it can be the same as the viewport element.
   */
  padding: HTMLElement;
  // The element responsible of the scrolling.
  viewport: HTMLElement;
  /**
   * The element responsible for holding the actual content.
   * Depending on initialization it can be the same as the viewport element.
   */
  content: HTMLElement;
  /**
   * The element through which you can get the current `scrollLeft` or `scrollTop` offset.
   * Depending on the target element it can be the same as the viewport element.
   */
  scrollOffsetElement: HTMLElement;
  /**
   * The element through which you can add `scroll` events.
   * Depending on the target element it can be the same as the viewport element.
   */
  scrollEventElement: HTMLElement | Document;
  // The horizontal scrollbar's elements.
  scrollbarHorizontal: CloneableScrollbarElements;
  // The vertical scrollbar's elements.
  scrollbarVertical: CloneableScrollbarElements;
}
```

--------------------------------

### OverlayScrollbars Event Listener Type Definitions (TypeScript)

Source: https://kingsora.github.io/OverlayScrollbars

Defines the TypeScript types for OverlayScrollbars event listeners, mapping event names to their respective listener arguments. Includes detailed types for update arguments.

```typescript
// A mapping between event names and their listener arguments.
type EventListenerArgs = {
  // Dispatched after all elements are initialized and appended.
  initialized: [instance: OverlayScrollbars];
  // Dispatched after an update.
  updated: [instance: OverlayScrollbars, onUpdatedArgs: OnUpdatedEventListenerArgs];
  // Dispatched after all elements, observers and events are destroyed.
  destroyed: [instance: OverlayScrollbars, canceled: boolean];
  // Dispatched on scroll.
  scroll: [instance: OverlayScrollbars, event: Event];
};

interface OnUpdatedEventListenerArgs {
  // Hints which describe what changed in the DOM.
  updateHints: {
    // Whether the size of the host element changed.
    sizeChanged: boolean;
    // Whether the direction of the host element changed.
    directionChanged: boolean;
    // Whether the intrinsic height behavior changed.
    heightIntrinsicChanged: boolean;
    // Whether the overflow edge (clientWidth / clientHeight) of the viewport element changed.
    overflowEdgeChanged: boolean;
    // Whether the overflow amount changed.
    overflowAmountChanged: boolean;
    // Whether the overflow style changed.
    overflowStyleChanged: boolean;
    // Whether the scroll coordinates changed.
    scrollCoordinatesChanged: boolean;
    // Whether an host mutation took place.
    hostMutation: boolean;
    // Whether an content mutation took place.
    contentMutation: boolean;
  };
  // The changed options.
  changedOptions: PartialOptions;
  // Whether the update happened with force-invalidated cache.
  force: boolean;
}
```

--------------------------------

### Add Single Plugin

Source: https://kingsora.github.io/OverlayScrollbars

Adds a single plugin to OverlayScrollbars. This is useful for extending OverlayScrollbars' functionality with specific features like scrollbar hiding or size observation.

```APIDOC
## `plugin(plugin): object | undefined`

### Description
Adds a single plugin to OverlayScrollbars.

### Parameters
#### Path Parameters
- **plugin** (object) - Required - The plugin to be added.

### Returns
- **object | void** - An object describing the plugin's static module instance or `void` if no instance was found.
```

--------------------------------

### Scrollbar Visibility Types

Source: https://kingsora.github.io/OverlayScrollbars

Defines the possible states for scrollbar visibility based on pointer interaction or user scrolling.

```typescript
// The scrollbars are hidden unless the pointer moves in the host element or the user scrolls.
  | 'move'
  // The scrollbars are hidden if the pointer leaves the host element or unless the user scrolls.
  | 'leave';
```

--------------------------------

### OverlayScrollbars Plugin TypeScript Types

Source: https://kingsora.github.io/OverlayScrollbars

Defines TypeScript types for OverlayScrollbars plugins, including generic types for static and instance modules, and utility types for inferring module instance types.

```typescript
// Describes a OverlayScrollbar plugin.
type Plugin<
  // The name of the plugin.
  Name extends string = string,
  // The module instance type of the static module.
  S extends PluginModuleInstance | void = PluginModuleInstance | void, 
  // The module instance type of the instance module.
  I extends PluginModuleInstance | void = PluginModuleInstance | void 
> = {
  [pluginName in Name]: PluginModule<S, I>;
};
 
// Describes a OverlayScrollbar plugin which has only a static module.
type StaticPlugin<
  Name extends string = string,
  T extends PluginModuleInstance = PluginModuleInstance
> = Plugin<Name, T, void>;
 
// Describes a OverlayScrollbar plugin which has only a instance module.
type InstancePlugin<
  Name extends string = string,
  T extends PluginModuleInstance = PluginModuleInstance
> = Plugin<Name, void, T>;
 
// Infers the type of the static module's instance of the passed plugin.
type InferStaticPluginModuleInstance<T extends StaticPlugin>;
 
// Infers the type of the instance modules instance of the passed plugin.
type InferInstancePluginModuleInstance<T extends InstancePlugin>;
```

--------------------------------

### update.attributes

Source: https://kingsora.github.io/OverlayScrollbars

Specify additional attributes for the MutationObserver to observe. A base set of attributes is always observed.

```APIDOC
## update.attributes

### Description
An array of additional attributes that the `MutationObserver` should observe the content for.

### Parameters
#### Path Parameters
- **attributes** (string[]) - Optional - An array of attribute names to observe.

### Default Value
`null`

### Note
There is a base array of attributes that the `MutationObserver` always observes, even if this option is `null`.
```

--------------------------------

### scrollbars.autoHideSuspend

Source: https://kingsora.github.io/OverlayScrollbars

Suspends auto-hiding functionality until the first scroll interaction. Recommended to be true for better accessibility.

```APIDOC
## scrollbars.autoHideSuspend

### Description
Suspend the autoHide functionality until the first scroll interaction is performed.

### Parameters
#### Path Parameters
- **autoHideSuspend** (boolean) - Required - Whether to suspend auto-hiding.

### Default Value
`false`

### Note
The default value for this option is `false` for backwards compatibility reasons but is recommended to be `true` for better accessibility.
```

--------------------------------

### Scrollbar HTML Structure

Source: https://kingsora.github.io/OverlayScrollbars

The basic HTML markup for horizontal and vertical scrollbars in OverlayScrollbars.

```html
<div class="os-scrollbar os-scrollbar-horizontal">
    <div class="os-scrollbar-track">
        <div class="os-scrollbar-handle">
        </div>
    </div>
</div>
<div class="os-scrollbar os-scrollbar-vertical">
    <div class="os-scrollbar-track">
        <div class="os-scrollbar-handle">
        </div>
    </div>
</div>
```

--------------------------------

### Event Listeners

Source: https://kingsora.github.io/OverlayScrollbars

OverlayScrollbars allows you to attach event listeners to manage various lifecycle events and user interactions. You can add listeners for events like 'initialized', 'updated', 'destroyed', and 'scroll'.

```APIDOC
## Events
You can initialize OverlayScrollbars with an initial set of events, which can be managed at any time with the `on` and `off` methods.

### `initialized`
arguments| description  
---|---  
`instance`| The instance which dispatched the event.
Dispatched after all generated elements, observers and events were appended to the DOM.

### `updated`
arguments| description  
---|---  
`instance`| The instance which dispatched the event.
`onUpdatedArgs`| An `object` which describes the update in detail.
> **Note** : If an update was triggered but nothing changed, the event won't be dispatched.
Dispatched after the instance was updated.

### `destroyed`
arguments| description  
---|---  
`instance`| The instance which dispatched the event.
`canceled`| A `boolean` which indicates whether the initialization was canceled and thus destroyed.
Dispatched after all generated elements, observers and events were removed from the DOM.

### `scroll`
arguments| description  
---|---  
`instance`| The instance which dispatched the event.
`event`| The original `event` argument of the DOM event.
Dispatched by scrolling the viewport.
```

--------------------------------

### update.debounce.event

Source: https://kingsora.github.io/OverlayScrollbars

Debounce updates triggered by events registered in `update.elementEvents`. Configurable with timeout, maxWait, and leading options.

```APIDOC
## update.debounce.event

### Description
Debounce updates which were triggered by an event registered in the `update.elementEvents` option.

### Parameters
#### Query Parameters
- **timeout** (number) - Optional - The debounce timeout in milliseconds.
- **maxWait** (number) - Optional - The maximum time to wait before invoking the function.
- **leading** (boolean) - Optional - Specify invoking on the leading edge of the timeout.

### Default Value
`[33, 99]`
```

--------------------------------

### Add Single Event Listener to OverlayScrollbars Instance

Source: https://kingsora.github.io/OverlayScrollbars

Attach a single event listener to an OverlayScrollbars instance for a specific event name. Returns a function to remove the added listener.

```javascript
osInstance.on(name, listener);
```

--------------------------------

### Scrollbar Click Scroll Behavior Type

Source: https://kingsora.github.io/OverlayScrollbars

Defines the behavior when a user clicks on a scrollbar, allowing boolean, string, or a function for custom logic.

```typescript
// The scrollbar click scroll behavior.
type ScrollbarsClickScrollBehavior =
  | boolean
  | 'instant'
  | (( 
      isHorizontal: boolean
    ) => Partial<ScrollbarsClickScrollBehaviorOptions> | false | null | undefined | void);
```

--------------------------------

### destroy()

Source: https://kingsora.github.io/OverlayScrollbars

Destroys the instance and removes all added elements. This method cleans up the scrollbar instance and removes any associated DOM elements.

```APIDOC
## destroy()

### Description
Destroys the instance and removes all added elements.

### Method
`destroy`

### Returns
- **void**
```

--------------------------------

### Base Scrollbar Styling Properties

Source: https://kingsora.github.io/OverlayScrollbars

Defines the default CSS Custom Properties for scrollbar styling, including size, padding, border-radius, and background for tracks and handles.

```css
.os-scrollbar {
  --os-size: 0;
  --os-padding-perpendicular: 0;
  --os-padding-axis: 0;
  --os-track-border-radius: 0;
  --os-track-bg: none;
  --os-track-bg-hover: none;
  --os-track-bg-active: none;
  --os-track-border: none;
  --os-track-border-hover: none;
  --os-track-border-active: none;
  --os-handle-border-radius: 0;
  --os-handle-bg: none;
  --os-handle-bg-hover: none;
  --os-handle-bg-active: none;
  --os-handle-border: none;
  --os-handle-border-hover: none;
  --os-handle-border-active: none;
  --os-handle-min-size: 33px;
  --os-handle-max-size: none;
  --os-handle-perpendicular-size: 100%;
  --os-handle-perpendicular-size-hover: 100%;
  --os-handle-perpendicular-size-active: 100%;
  --os-handle-interactive-area-offset: 0;
}
```

--------------------------------

### OverlayScrollbars Visibility Behavior Type

Source: https://kingsora.github.io/OverlayScrollbars

Determines how scrollbars are displayed. Options include 'visible' (always shown), 'hidden' (always hidden), or 'auto' (shown only on overflow).

```typescript
type ScrollbarsVisibilityBehavior =
  | 'visible'
  | 'hidden'
  | 'auto';
```

--------------------------------

### OverlayScrollbars Overflow Behavior Type

Source: https://kingsora.github.io/OverlayScrollbars

Defines the possible behaviors for scrollable axes (x and y). Choose from 'hidden', 'visible', 'scroll', 'visible-hidden', or 'visible-scroll'.

```typescript
type OverflowBehavior =
  | 'hidden'
  | 'visible'
  | 'scroll'
  | 'visible-hidden'
  | 'visible-scroll';
```

--------------------------------

### update.ignoreMutation

Source: https://kingsora.github.io/OverlayScrollbars

Provide a function to ignore specific mutations based on a MutationRecord. Useful for fine-tuning performance.

```APIDOC
## update.ignoreMutation

### Description
A function which receives a `MutationRecord` as an argument. If the function returns a truthy value the mutation will be ignored and the plugin won't update.

### Parameters
#### Path Parameters
- **mutation** (function) - Optional - A callback function that receives a `MutationRecord`.

### Default Value
`null`

### Note
Useful to fine-tune performance.
```

--------------------------------

### overflow.x

Source: https://kingsora.github.io/OverlayScrollbars

Sets the overflow behavior for the horizontal (x) axis. Valid values include 'hidden', 'scroll', 'visible', 'visible-hidden', and 'visible-scroll'.

```APIDOC
## overflow.x

### Description
The overflow behavior for the horizontal (x) axis.

### Parameters
#### Path Parameters
- **overflow.x** (string) - Required - The overflow behavior for the x-axis.

### Default Value
`'scroll'`

### Note
Valid values are: `'hidden'`, `'scroll'`, `'visible'`, `'visible-hidden'` and `'visible-scroll'`.
```

--------------------------------

### scrollbars.dragScroll

Source: https://kingsora.github.io/OverlayScrollbars

Enables or disables dragging scrollbar handles for scrolling.

```APIDOC
## scrollbars.dragScroll

### Description
Indicates whether you can drag the scrollbar handles for scrolling.

### Parameters
#### Path Parameters
- **dragScroll** (boolean) - Required - Whether drag scrolling is enabled.

### Default Value
`true`
```

--------------------------------

### OverlayScrollbars Auto Hide Behavior Type

Source: https://kingsora.github.io/OverlayScrollbars

Configures the auto-hide behavior for scrollbars. 'never' keeps them visible, while 'scroll' hides them unless the user scrolls.

```typescript
type ScrollbarsAutoHideBehavior =
  | 'never'
  | 'scroll';
```

--------------------------------

### Adjust Scrollbar Handle Length

Source: https://kingsora.github.io/OverlayScrollbars

Apply these CSS rules to limit or adjust the minimum and maximum lengths of the scrollbar handle. Note that 'width' and 'height' properties are automatically managed by the plugin and will not work for this purpose.

```css
/* horizontal boundaries */
.os-scrollbar-horizontal .os-scrollbar-handle {
  min-width: 50px;
  max-width: 200px;
}
/* vertical boundaries */
.os-scrollbar-vertical .os-scrollbar-handle {
  min-height: 40px;
  max-height: 40px;
}
```

--------------------------------

### scrollbars.visibility

Source: https://kingsora.github.io/OverlayScrollbars

Controls the visibility of scrollbars when their axis has scrollable overflow. Valid values are 'visible', 'hidden', and 'auto'.

```APIDOC
## scrollbars.visibility

### Description
The visibility of a scrollbar if its scroll axis is able to have a scrollable overflow.

### Parameters
#### Path Parameters
- **visibility** (string) - Required - The visibility state of the scrollbar.

### Default Value
`'auto'`

### Note
Valid values are: `'visible'`, `'hidden'`, and `'auto'`. Scrollable overflow for an axis is only possible with the overflow behavior set to `'scroll'` or `'visible-scroll'`.
```

--------------------------------

### scrollbars.autoHide

Source: https://kingsora.github.io/OverlayScrollbars

Determines when scrollbars are automatically hidden. Options include 'never', 'scroll', 'leave', and 'move'.

```APIDOC
## scrollbars.autoHide

### Description
Dictates whether to hide visible scrollbars automatically after a certain user action.

### Parameters
#### Path Parameters
- **autoHide** (string) - Required - The condition for auto-hiding scrollbars.

### Default Value
`'never'`

### Note
Valid values are: `'never'`, `'scroll'`, `'leave'` and `'move'`.
```

--------------------------------

### OverlayScrollbars Debounce Value Type

Source: https://kingsora.github.io/OverlayScrollbars

Specifies how to configure debouncing for updates. Can be a number for timeout, a tuple for timeout, maxWait, and leading edge execution, or false/null to disable.

```typescript
type OptionsDebounceValue =
  | [
      timeout?: number | false | null | undefined,
      maxWait?: number | false | null | undefined,
      leading?: boolean | null | undefined,
    ]
  | number
  | false
  | null;
```

--------------------------------

### off(name, listener)

Source: https://kingsora.github.io/OverlayScrollbars

Removes a single event listener from the instance. Use this method to detach a specific callback function from an event.

```APIDOC
## off(name, listener)

### Description
Removes a single event listener from the instance.

### Method
`off`

### Parameters
#### Path Parameters
- **name** (`string`) - Required - The event name.
- **listener** (`Function`) - Required - The function to be removed.

### Returns
- **void**
```
Tokens:
Raw