0
# Configuration Options
1

2
Comprehensive configuration system for customizing OverlayScrollbars behavior, appearance, and functionality through nested options objects.
3

4
## Core Options
5

6
### className
7

8
```javascript { .api }
9
interface OverlayScrollbarsOptions {
10
  className?: string | null;
11
}
12
```
13

14
CSS class name applied to the host element for custom styling.
15

16
**Type:** String | null  
17
**Default:** `"os-theme-dark"`
18

19
```javascript
20
// Apply custom theme
21
OverlayScrollbars(element, {
22
  className: "custom-scrollbar-theme"
23
});
24

25
// Remove default theme
26
OverlayScrollbars(element, {
27
  className: null
28
});
29
```
30

31
### resize
32

33
```javascript { .api }
34
interface OverlayScrollbarsOptions {
35
  resize?: "none" | "both" | "horizontal" | "vertical";
36
}
37
```
38

39
Controls resize behavior for the scrollbars.
40

41
**Type:** String  
42
**Default:** `"none"`  
43
**Values:** `"none"`, `"both"`, `"horizontal"`, `"vertical"`
44

45
```javascript
46
OverlayScrollbars(element, {
47
  resize: "both" // Allow resizing in both directions
48
});
49
```
50

51
### sizeAutoCapable
52

53
```javascript { .api }
54
interface OverlayScrollbarsOptions {
55
  sizeAutoCapable?: boolean;
56
}
57
```
58

59
Whether the plugin can automatically detect size changes.
60

61
**Type:** Boolean  
62
**Default:** `true`
63

64
### clipAlways
65

66
```javascript { .api }
67
interface OverlayScrollbarsOptions {
68
  clipAlways?: boolean;
69
}
70
```
71

72
Whether to always clip the content.
73

74
**Type:** Boolean  
75
**Default:** `true`
76

77
### normalizeRTL
78

79
```javascript { .api }
80
interface OverlayScrollbarsOptions {
81
  normalizeRTL?: boolean;
82
}
83
```
84

85
Whether to normalize RTL (right-to-left) scrolling behavior.
86

87
**Type:** Boolean  
88
**Default:** `true`
89

90
### paddingAbsolute
91

92
```javascript { .api }
93
interface OverlayScrollbarsOptions {
94
  paddingAbsolute?: boolean;
95
}
96
```
97

98
Whether to use absolute positioning for padding.
99

100
**Type:** Boolean  
101
**Default:** `false`
102

103
## Auto Update Options
104

105
### autoUpdate
106

107
```javascript { .api }
108
interface OverlayScrollbarsOptions {
109
  autoUpdate?: boolean | null;
110
}
111
```
112

113
Automatic update detection behavior.
114

115
**Type:** Boolean | null  
116
**Default:** `null`
117

118
```javascript
119
// Enable auto-update
120
OverlayScrollbars(element, {
121
  autoUpdate: true
122
});
123

124
// Disable auto-update
125
OverlayScrollbars(element, {
126
  autoUpdate: false
127
});
128

129
// Use recommended setting (null)
130
OverlayScrollbars(element, {
131
  autoUpdate: null
132
});
133
```
134

135
### autoUpdateInterval
136

137
```javascript { .api }
138
interface OverlayScrollbarsOptions {
139
  autoUpdateInterval?: number;
140
}
141
```
142

143
Interval in milliseconds for automatic updates.
144

145
**Type:** Number  
146
**Default:** `33`
147

148
### updateOnLoad
149

150
```javascript { .api }
151
interface OverlayScrollbarsOptions {
152
  updateOnLoad?: string | string[] | null;
153
}
154
```
155

156
Elements that trigger updates when loaded.
157

158
**Type:** String | Array | null  
159
**Default:** `["img"]`
160

161
```javascript
162
// Update when images and videos load
163
OverlayScrollbars(element, {
164
  updateOnLoad: ["img", "video"]
165
});
166

167
// Don't update on any element load
168
OverlayScrollbars(element, {
169
  updateOnLoad: null
170
});
171
```
172

173
## Native Scrollbars Options
174

175
### nativeScrollbarsOverlaid
176

177
```javascript { .api }
178
interface OverlayScrollbarsOptions {
179
  nativeScrollbarsOverlaid?: {
180
    showNativeScrollbars?: boolean;
181
    initialize?: boolean;
182
  };
183
}
184
```
185

186
Configuration for when native scrollbars are overlaid (like on macOS).
187

188
```javascript
189
OverlayScrollbars(element, {
190
  nativeScrollbarsOverlaid: {
191
    showNativeScrollbars: false, // Hide native scrollbars
192
    initialize: true // Initialize even when native are overlaid
193
  }
194
});
195
```
196

197
## Overflow Behavior Options
198

199
### overflowBehavior
200

201
```javascript { .api }
202
interface OverlayScrollbarsOptions {
203
  overflowBehavior?: {
204
    x?: "visible-hidden" | "visible-scroll" | "scroll" | "hidden";
205
    y?: "visible-hidden" | "visible-scroll" | "scroll" | "hidden";
206
  };
207
}
208
```
209

210
Controls overflow behavior for horizontal and vertical axes.
211

212
**Default:** `{ x: "scroll", y: "scroll" }`
213

214
```javascript
215
OverlayScrollbars(element, {
216
  overflowBehavior: {
217
    x: "hidden", // Hide horizontal overflow
218
    y: "scroll"  // Allow vertical scrolling
219
  }
220
});
221
```
222

223
## Scrollbars Options
224

225
### scrollbars
226

227
```javascript { .api }
228
interface OverlayScrollbarsOptions {
229
  scrollbars?: {
230
    visibility?: "visible" | "hidden" | "auto";
231
    autoHide?: "never" | "scroll" | "leave" | "move";
232
    autoHideDelay?: number;
233
    dragScrolling?: boolean;
234
    clickScrolling?: boolean;
235
    touchSupport?: boolean;
236
    snapHandle?: boolean;
237
  };
238
}
239
```
240

241
Comprehensive scrollbar behavior configuration.
242

243
```javascript
244
OverlayScrollbars(element, {
245
  scrollbars: {
246
    visibility: "auto",        // Show scrollbars when needed
247
    autoHide: "leave",         // Hide when mouse leaves
248
    autoHideDelay: 800,        // Delay before hiding (ms)
249
    dragScrolling: true,       // Enable drag scrolling
250
    clickScrolling: false,     // Disable click scrolling on track
251
    touchSupport: true,        // Enable touch support
252
    snapHandle: false          // Don't snap handle to increments
253
  }
254
});
255
```
256

257
#### visibility
258

259
Controls when scrollbars are visible.
260

261
**Values:**
262
- `"visible"` - Always visible
263
- `"hidden"` - Always hidden
264
- `"auto"` - Visible when content overflows
265

266
#### autoHide
267

268
Controls automatic hiding behavior.
269

270
**Values:**
271
- `"never"` - Never auto-hide
272
- `"scroll"` - Hide after scrolling stops
273
- `"leave"` - Hide when mouse leaves scrollbar area
274
- `"move"` - Hide when mouse stops moving
275

276
#### autoHideDelay
277

278
Time in milliseconds before auto-hiding scrollbars.
279

280
**Type:** Number  
281
**Default:** `800`
282

283
## Textarea Options
284

285
### textarea
286

287
```javascript { .api }
288
interface OverlayScrollbarsOptions {
289
  textarea?: {
290
    dynWidth?: boolean;
291
    dynHeight?: boolean;
292
    inheritedAttrs?: string | string[] | null;
293
  };
294
}
295
```
296

297
Special options for textarea elements.
298

299
```javascript
300
OverlayScrollbars(textareaElement, {
301
  textarea: {
302
    dynWidth: false,  // Don't adjust width dynamically
303
    dynHeight: false, // Don't adjust height dynamically
304
    inheritedAttrs: ["style", "class"] // Attributes to inherit
305
  }
306
});
307
```
308

309
## Callbacks
310

311
### callbacks
312

313
```javascript { .api }
314
interface OverlayScrollbarsOptions {
315
  callbacks?: {
316
    onInitialized?: (instance: OverlayScrollbarsInstance) => void;
317
    onInitializationWithdrawn?: (instance: OverlayScrollbarsInstance) => void;
318
    onDestroyed?: (instance: OverlayScrollbarsInstance) => void;
319
    onScrollStart?: (instance: OverlayScrollbarsInstance) => void;
320
    onScroll?: (instance: OverlayScrollbarsInstance) => void;
321
    onScrollStop?: (instance: OverlayScrollbarsInstance) => void;
322
    onOverflowChanged?: (instance: OverlayScrollbarsInstance) => void;
323
    onOverflowAmountChanged?: (instance: OverlayScrollbarsInstance) => void;
324
    onDirectionChanged?: (instance: OverlayScrollbarsInstance) => void;
325
    onContentSizeChanged?: (instance: OverlayScrollbarsInstance) => void;
326
    onHostSizeChanged?: (instance: OverlayScrollbarsInstance) => void;
327
    onUpdated?: (instance: OverlayScrollbarsInstance) => void;
328
  };
329
}
330
```
331

332
Lifecycle and event callbacks.
333

334
```javascript
335
OverlayScrollbars(element, {
336
  callbacks: {
337
    onInitialized: function(instance) {
338
      console.log('OverlayScrollbars initialized');
339
    },
340
    
341
    onScrollStart: function(instance) {
342
      console.log('Scrolling started');
343
    },
344
    
345
    onScroll: function(instance) {
346
      const state = instance.getState();
347
      console.log('Scroll position:', state.contentScrollSize);
348
    },
349
    
350
    onScrollStop: function(instance) {
351
      console.log('Scrolling stopped');
352
    },
353
    
354
    onOverflowChanged: function(instance) {
355
      const state = instance.getState();
356
      console.log('Overflow changed:', state.hasOverflow);
357
    },
358
    
359
    onContentSizeChanged: function(instance) {
360
      console.log('Content size changed');
361
      // Useful for triggering other UI updates
362
    },
363
    
364
    onDestroyed: function(instance) {
365
      console.log('Instance destroyed');
366
    }
367
  }
368
});
369
```
370

371
## Complete Configuration Example
372

373
```javascript
374
const completeConfig = {
375
  className: "custom-theme",
376
  resize: "both",
377
  sizeAutoCapable: true,
378
  clipAlways: true,
379
  normalizeRTL: true,
380
  paddingAbsolute: false,
381
  autoUpdate: null,
382
  autoUpdateInterval: 33,
383
  updateOnLoad: ["img", "video"],
384
  
385
  nativeScrollbarsOverlaid: {
386
    showNativeScrollbars: false,
387
    initialize: true
388
  },
389
  
390
  overflowBehavior: {
391
    x: "scroll",
392
    y: "scroll"
393
  },
394
  
395
  scrollbars: {
396
    visibility: "auto",
397
    autoHide: "leave",
398
    autoHideDelay: 1000,
399
    dragScrolling: true,
400
    clickScrolling: true,
401
    touchSupport: true,
402
    snapHandle: false
403
  },
404
  
405
  textarea: {
406
    dynWidth: false,
407
    dynHeight: false,
408
    inheritedAttrs: ["style", "class"]
409
  },
410
  
411
  callbacks: {
412
    onInitialized: function(instance) {
413
      console.log('Initialized');
414
    },
415
    onScroll: function(instance) {
416
      // Handle scroll events
417
    },
418
    onUpdated: function(instance) {
419
      // Handle updates
420
    }
421
  }
422
};
423

424
const instance = OverlayScrollbars(element, completeConfig);
425
```
426

427
## Types
428

429
```javascript { .api }
430
interface OverlayScrollbarsOptions {
431
  className?: string | null;
432
  resize?: "none" | "both" | "horizontal" | "vertical";
433
  sizeAutoCapable?: boolean;
434
  clipAlways?: boolean;
435
  normalizeRTL?: boolean;
436
  paddingAbsolute?: boolean;
437
  autoUpdate?: boolean | null;
438
  autoUpdateInterval?: number;
439
  updateOnLoad?: string | string[] | null;
440
  nativeScrollbarsOverlaid?: NativeScrollbarsOverlaidOptions;
441
  overflowBehavior?: OverflowBehaviorOptions;
442
  scrollbars?: ScrollbarsOptions;
443
  textarea?: TextareaOptions;
444
  callbacks?: CallbackOptions;
445
}
446

447
interface NativeScrollbarsOverlaidOptions {
448
  showNativeScrollbars?: boolean;
449
  initialize?: boolean;
450
}
451

452
interface OverflowBehaviorOptions {
453
  x?: "visible-hidden" | "visible-scroll" | "scroll" | "hidden";
454
  y?: "visible-hidden" | "visible-scroll" | "scroll" | "hidden";
455
}
456

457
interface ScrollbarsOptions {
458
  visibility?: "visible" | "hidden" | "auto";
459
  autoHide?: "never" | "scroll" | "leave" | "move";
460
  autoHideDelay?: number;
461
  dragScrolling?: boolean;
462
  clickScrolling?: boolean;
463
  touchSupport?: boolean;
464
  snapHandle?: boolean;
465
}
466

467
interface TextareaOptions {
468
  dynWidth?: boolean;
469
  dynHeight?: boolean;
470
  inheritedAttrs?: string | string[] | null;
471
}
472

473
interface CallbackOptions {
474
  onInitialized?: (instance: OverlayScrollbarsInstance) => void;
475
  onInitializationWithdrawn?: (instance: OverlayScrollbarsInstance) => void;
476
  onDestroyed?: (instance: OverlayScrollbarsInstance) => void;
477
  onScrollStart?: (instance: OverlayScrollbarsInstance) => void;
478
  onScroll?: (instance: OverlayScrollbarsInstance) => void;
479
  onScrollStop?: (instance: OverlayScrollbarsInstance) => void;
480
  onOverflowChanged?: (instance: OverlayScrollbarsInstance) => void;
481
  onOverflowAmountChanged?: (instance: OverlayScrollbarsInstance) => void;
482
  onDirectionChanged?: (instance: OverlayScrollbarsInstance) => void;
483
  onContentSizeChanged?: (instance: OverlayScrollbarsInstance) => void;
484
  onHostSizeChanged?: (instance: OverlayScrollbarsInstance) => void;
485
  onUpdated?: (instance: OverlayScrollbarsInstance) => void;
486
}
487
```