0
# OverlayScrollbars
1

2
OverlayScrollbars is a JavaScript scrollbar plugin that hides native scrollbars and provides custom, styleable overlay scrollbars while maintaining native functionality and feeling. It supports both vanilla JavaScript and jQuery implementations with extensive browser compatibility (IE8+), automatic update detection, powerful scroll animations, and a rich extension system.
3

4
## Package Information
5

6
- **Package Name**: overlayscrollbars
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript definitions)
9
- **Installation**: `npm install overlayscrollbars`
10

11
## Core Imports
12

13
**ES Modules:**
14
```javascript
15
import OverlayScrollbars from "overlayscrollbars";
16
```
17

18
**CommonJS:**
19
```javascript
20
const OverlayScrollbars = require("overlayscrollbars");
21
```
22

23
**UMD (Browser Global):**
24
```html
25
<script src="node_modules/overlayscrollbars/js/OverlayScrollbars.min.js"></script>
26
<link rel="stylesheet" href="node_modules/overlayscrollbars/css/OverlayScrollbars.min.css">
27
<script>
28
// OverlayScrollbars is available globally
29
</script>
30
```
31

32
**jQuery Plugin:**
33
```javascript
34
import "overlayscrollbars/js/jquery.overlayScrollbars.min.js";
35
// or
36
<script src="overlayscrollbars/js/jquery.overlayScrollbars.min.js"></script>
37
```
38

39
## Basic Usage
40

41
```javascript
42
import OverlayScrollbars from "overlayscrollbars";
43

44
// Initialize on a single element
45
const osInstance = OverlayScrollbars(document.querySelector('.content'), {
46
  className: "os-theme-dark",
47
  scrollbars: {
48
    autoHide: "leave"
49
  }
50
});
51

52
// Initialize on multiple elements
53
const instances = OverlayScrollbars(document.querySelectorAll('.scrollable'), {
54
  resize: "both",
55
  scrollbars: {
56
    visibility: "auto",
57
    autoHide: "scroll"
58
  }
59
});
60

61
// jQuery usage
62
$('.content').overlayScrollbars({
63
  className: "os-theme-dark",
64
  callbacks: {
65
    onScrollStart: function() {
66
      console.log("Scrolling started");
67
    }
68
  }
69
});
70
```
71

72
## Architecture
73

74
OverlayScrollbars is built around several key components:
75

76
- **Constructor Function**: Main `OverlayScrollbars()` function for creating instances
77
- **Instance Methods**: Methods for controlling and querying individual scrollbar instances
78
- **Static Methods**: Global configuration and utility methods (`globals()`, `defaultOptions()`, etc.)
79
- **Options System**: Comprehensive configuration object with nested options for different aspects
80
- **Extension System**: Plugin architecture for extending functionality
81
- **jQuery Integration**: Seamless jQuery plugin interface
82
- **Event System**: Comprehensive callback system for lifecycle and scroll events
83

84
## Capabilities
85

86
### Core Initialization and Management
87

88
Primary constructor and instance management functionality for creating, configuring, and controlling OverlayScrollbars instances.
89

90
```javascript { .api }
91
function OverlayScrollbars(
92
  target: Element | NodeList | string,
93
  options?: OverlayScrollbarsOptions,
94
  extensions?: OverlayScrollbarsExtensions
95
): OverlayScrollbarsInstance | OverlayScrollbarsInstance[];
96
```
97

98
[Initialization and Management](./initialization.md)
99

100
### Instance Control Methods
101

102
Instance methods for updating, scrolling, controlling behavior, and managing extensions on individual OverlayScrollbars instances.
103

104
```javascript { .api }
105
interface OverlayScrollbarsInstance {
106
  update(force?: boolean): OverlayScrollbarsInstance;
107
  scroll(coordinates: ScrollCoordinates, duration?: number, easing?: string | function, complete?: function): OverlayScrollbarsInstance;
108
  scrollStop(): OverlayScrollbarsInstance;
109
  destroy(): OverlayScrollbarsInstance;
110
  ext(extensionName?: string): OverlayScrollbarsExtension | OverlayScrollbarsExtension[] | undefined;
111
  addExt(extensionName: string, extensionOptions?: object): OverlayScrollbarsExtension | undefined;
112
  removeExt(extensionName: string): boolean;
113
}
114
```
115

116
[Instance Methods](./instance-methods.md)
117

118
### Static Configuration Methods
119

120
Global methods for configuring default options, validating instances, and managing extensions across all OverlayScrollbars instances.
121

122
```javascript { .api }
123
interface OverlayScrollbarsStatic {
124
  globals(): OverlayScrollbarsGlobals;
125
  defaultOptions(newOptions?: OverlayScrollbarsOptions): OverlayScrollbarsOptions;
126
  valid(instance: any): boolean;
127
  extension(name: string, extension?: function, defaultOptions?: object): any;
128
}
129
```
130

131
[Static Methods](./static-methods.md)
132

133
### Configuration Options
134

135
Comprehensive configuration system with nested options for scrollbar behavior, appearance, callbacks, and specialized functionality.
136

137
```javascript { .api }
138
interface OverlayScrollbarsOptions {
139
  className?: string | null;
140
  resize?: "none" | "both" | "horizontal" | "vertical";
141
  sizeAutoCapable?: boolean;
142
  scrollbars?: ScrollbarsOptions;
143
  overflowBehavior?: OverflowBehaviorOptions;
144
  callbacks?: CallbackOptions;
145
}
146
```
147

148
[Configuration Options](./options.md)
149

150
### Extension System
151

152
Plugin architecture for extending OverlayScrollbars functionality with custom extensions that can be registered globally and used across instances.
153

154
```javascript { .api }
155
interface OverlayScrollbarsExtension {
156
  added(instance: OverlayScrollbarsInstance): void;
157
  removed?(): void;
158
}
159
```
160

161
[Extensions](./extensions.md)
162

163
### jQuery Integration
164

165
jQuery plugin interface providing seamless integration with jQuery selectors and chaining while maintaining full API compatibility.
166

167
```javascript { .api }
168
interface JQuery {
169
  overlayScrollbars(options: OverlayScrollbarsOptions, extensions?: OverlayScrollbarsExtensions): JQuery;
170
  overlayScrollbars(): OverlayScrollbarsInstance | OverlayScrollbarsInstance[];
171
}
172
```
173

174
[jQuery Integration](./jquery.md)
175

176
## Types
177

178
```javascript { .api }
179
type ScrollCoordinates = {
180
  x?: number | string;
181
  y?: number | string;
182
} | number | string | Element;
183

184
interface OverlayScrollbarsGlobals {
185
  defaultOptions: OverlayScrollbarsOptions;
186
  autoUpdateRecommended: boolean;
187
  supportMutationObserver: boolean;
188
  supportResizeObserver: boolean;
189
  supportPassiveEvents: boolean;
190
  supportTransform: boolean;
191
  supportTransition: boolean;
192
  restrictedMeasuring: boolean;
193
  nativeScrollbarStyling: boolean;
194
  cssCalc: string | null;
195
  nativeScrollbarSize: { x: number; y: number };
196
  nativeScrollbarIsOverlaid: { x: boolean; y: boolean };
197
  overlayScrollbarDummySize: { x: number; y: number };
198
  rtlScrollBehavior: { i: boolean; n: boolean };
199
}
200

201
interface ScrollbarsOptions {
202
  visibility?: "visible" | "hidden" | "auto";
203
  autoHide?: "never" | "scroll" | "leave" | "move";
204
  autoHideDelay?: number;
205
  dragScrolling?: boolean;
206
  clickScrolling?: boolean;
207
  touchSupport?: boolean;
208
  snapHandle?: boolean;
209
}
210

211
interface OverflowBehaviorOptions {
212
  x?: "visible-hidden" | "visible-scroll" | "scroll" | "hidden";
213
  y?: "visible-hidden" | "visible-scroll" | "scroll" | "hidden";
214
}
215

216
interface CallbackOptions {
217
  onInitialized?: (instance: OverlayScrollbarsInstance) => void;
218
  onInitializationWithdrawn?: (instance: OverlayScrollbarsInstance) => void;
219
  onDestroyed?: (instance: OverlayScrollbarsInstance) => void;
220
  onScrollStart?: (instance: OverlayScrollbarsInstance) => void;
221
  onScroll?: (instance: OverlayScrollbarsInstance) => void;
222
  onScrollStop?: (instance: OverlayScrollbarsInstance) => void;
223
  onOverflowChanged?: (instance: OverlayScrollbarsInstance) => void;
224
  onOverflowAmountChanged?: (instance: OverlayScrollbarsInstance) => void;
225
  onDirectionChanged?: (instance: OverlayScrollbarsInstance) => void;
226
  onContentSizeChanged?: (instance: OverlayScrollbarsInstance) => void;
227
  onHostSizeChanged?: (instance: OverlayScrollbarsInstance) => void;
228
  onUpdated?: (instance: OverlayScrollbarsInstance) => void;
229
}
230

231
type OverlayScrollbarsExtensions = object | object[];
232
```