0
# Instance Methods
1

2
Methods available on individual OverlayScrollbars instances for controlling scrolling behavior, updating the instance, and managing the instance lifecycle.
3

4
## Update Methods
5

6
### update()
7

8
```javascript { .api }
9
OverlayScrollbarsInstance.prototype.update(force?: boolean): OverlayScrollbarsInstance;
10
```
11

12
Manually updates the instance to recalculate sizes and scrollbar visibility.
13

14
**Parameters:**
15
- `force` (Boolean, optional) - Force update even if no changes are detected
16

17
**Returns:** The instance for method chaining
18

19
```javascript
20
// Standard update
21
instance.update();
22

23
// Force update (bypasses change detection)
24
instance.update(true);
25

26
// Chaining
27
instance.update().scroll({ y: 100 });
28
```
29

30
## Scrolling Methods
31

32
### scroll()
33

34
```javascript { .api }
35
OverlayScrollbarsInstance.prototype.scroll(): ScrollPositionInfo;
36
OverlayScrollbarsInstance.prototype.scroll(
37
  coordinates: ScrollCoordinates,
38
  duration?: number,
39
  easing?: string | function,
40
  complete?: function
41
): OverlayScrollbarsInstance;
42
```
43

44
Scrolls to specified coordinates with optional animation, or returns current scroll position when called without parameters.
45

46
**Parameters:**
47
- `coordinates` - Target scroll position (various formats supported)
48
- `duration` (Number, optional) - Animation duration in milliseconds
49
- `easing` (String|Function, optional) - Easing function name or custom function
50
- `complete` (Function, optional) - Callback executed when scroll animation completes
51

52
**Returns:** The instance for method chaining (when scrolling) or scroll position information (when getting)
53

54
```javascript
55
// Get current scroll position
56
const position = instance.scroll();
57
console.log(position.position); // { x: 100, y: 200 }
58
console.log(position.ratio); // { x: 0.5, y: 0.3 }
59
console.log(position.max); // { x: 800, y: 1200 }
60

61
// Scroll to specific coordinates
62
instance.scroll({ x: 100, y: 200 });
63

64
// Scroll with animation
65
instance.scroll({ y: 500 }, 1000, 'easeOutQuart');
66

67
// Scroll to element
68
instance.scroll(document.querySelector('.target-element'));
69

70
// Scroll to bottom
71
instance.scroll({ y: '100%' });
72

73
// Scroll with completion callback
74
instance.scroll({ x: 0, y: 0 }, 800, 'swing', function() {
75
  console.log('Scrolled to top');
76
});
77

78
// Various coordinate formats
79
instance.scroll(100); // Scroll to x: 100
80
instance.scroll('50%'); // Scroll to 50% of content
81
instance.scroll({ y: 'begin' }); // Scroll to beginning
82
instance.scroll({ y: 'end' }); // Scroll to end
83
```
84

85
### scrollStop()
86

87
```javascript { .api }
88
OverlayScrollbarsInstance.prototype.scrollStop(): OverlayScrollbarsInstance;
89
```
90

91
Stops all currently running scroll animations.
92

93
**Returns:** The instance for method chaining
94

95
```javascript
96
// Stop any running scroll animations
97
instance.scrollStop();
98

99
// Can be chained with other methods
100
instance.scrollStop().scroll({ y: 0 });
101
```
102

103
## Options Management
104

105
### options()
106

107
```javascript { .api }
108
OverlayScrollbarsInstance.prototype.options(
109
  newOptions?: OverlayScrollbarsOptions | string,
110
  value?: any
111
): OverlayScrollbarsOptions | OverlayScrollbarsInstance;
112
```
113

114
Gets current options or updates instance options.
115

116
**Parameters:**
117
- `newOptions` (Object|String, optional) - New options object or property name
118
- `value` (any, optional) - Value when setting single property
119

120
**Returns:** Current options object (getter) or instance for chaining (setter)
121

122
```javascript
123
// Get all current options
124
const currentOptions = instance.options();
125

126
// Set multiple options
127
instance.options({
128
  className: "new-theme",
129
  scrollbars: {
130
    autoHide: "scroll",
131
    autoHideDelay: 500
132
  }
133
});
134

135
// Set single option by property path
136
instance.options('scrollbars.autoHide', 'leave');
137
instance.options('className', 'custom-theme');
138

139
// Nested property setting
140
instance.options('callbacks.onScrollStart', function() {
141
  console.log('Scroll started');
142
});
143
```
144

145
## Lifecycle Methods
146

147
### destroy()
148

149
```javascript { .api }
150
OverlayScrollbarsInstance.prototype.destroy(): OverlayScrollbarsInstance;
151
```
152

153
Destroys the instance and restores the original element to its initial state.
154

155
**Returns:** The destroyed instance
156

157
```javascript
158
// Destroy instance and clean up
159
instance.destroy();
160

161
// Check if instance is destroyed
162
if (instance.getState().destroyed) {
163
  console.log('Instance has been destroyed');
164
}
165
```
166

167
### sleep()
168

169
```javascript { .api }
170
OverlayScrollbarsInstance.prototype.sleep(): OverlayScrollbarsInstance;
171
```
172

173
Puts the instance to sleep, disabling automatic update detection.
174

175
**Returns:** The instance for method chaining
176

177
```javascript
178
// Put instance to sleep (stops auto-updates)
179
instance.sleep();
180

181
// Wake up by manually updating
182
instance.update();
183

184
// Check sleep state
185
const isSleeping = instance.getState('sleeping');
186
```
187

188
## State and Element Access
189

190
### getState()
191

192
```javascript { .api }
193
OverlayScrollbarsInstance.prototype.getState(property?: string): OverlayScrollbarsState | any;
194
```
195

196
Gets current state information about the instance.
197

198
**Parameters:**
199
- `property` (String, optional) - Specific state property to retrieve
200

201
**Returns:** Complete state object or specific property value
202

203
### getElements()
204

205
```javascript { .api }
206
OverlayScrollbarsInstance.prototype.getElements(elementName?: string): OverlayScrollbarsElements | Element;
207
```
208

209
Gets internal DOM elements created and managed by the instance.
210

211
**Parameters:**
212
- `elementName` (String, optional) - Specific element name to retrieve
213

214
**Returns:** Complete elements object or specific element
215

216
```javascript
217
// Get current scroll position from state
218
const state = instance.getState();
219
console.log(state.contentScrollSize); // { width: 1200, height: 800 }
220
console.log(state.hasOverflow); // { x: true, y: false }
221

222
// Get specific state property
223
const hasXOverflow = instance.getState('hasOverflow').x;
224

225
// Get all internal elements
226
const elements = instance.getElements();
227
const viewport = elements.viewport;
228

229
// Get specific element
230
const hostElement = instance.getElements('host');
231
```
232

233
## Extension Management
234

235
### ext()
236

237
```javascript { .api }
238
OverlayScrollbarsInstance.prototype.ext(extensionName?: string): OverlayScrollbarsExtension | OverlayScrollbarsExtension[] | undefined;
239
```
240

241
Gets extension instance(s) that have been added to this OverlayScrollbars instance.
242

243
**Parameters:**
244
- `extensionName` (String, optional) - Name of specific extension to retrieve
245

246
**Returns:** Extension instance, array of all extensions, or undefined if not found
247

248
```javascript
249
// Get all extensions added to this instance
250
const allExtensions = instance.ext();
251

252
// Get specific extension
253
const myExtension = instance.ext('myExtension');
254
if (myExtension) {
255
  // Use extension-specific methods
256
  myExtension.customMethod();
257
}
258
```
259

260
### addExt()
261

262
```javascript { .api }
263
OverlayScrollbarsInstance.prototype.addExt(
264
  extensionName: string,
265
  extensionOptions?: object
266
): OverlayScrollbarsExtension | undefined;
267
```
268

269
Adds an extension to this specific instance.
270

271
**Parameters:**
272
- `extensionName` (String) - Name of the registered extension to add
273
- `extensionOptions` (Object, optional) - Options for the extension instance
274

275
**Returns:** The added extension instance or undefined if the extension couldn't be added
276

277
```javascript
278
// Add extension with default options
279
const extension = instance.addExt('myExtension');
280

281
// Add extension with custom options
282
const extension = instance.addExt('autoScroller', {
283
  enabled: true,
284
  speed: 5,
285
  interval: 200
286
});
287

288
if (extension) {
289
  console.log('Extension added successfully');
290
}
291
```
292

293
### removeExt()
294

295
```javascript { .api }
296
OverlayScrollbarsInstance.prototype.removeExt(extensionName: string): boolean;
297
```
298

299
Removes an extension from this specific instance.
300

301
**Parameters:**
302
- `extensionName` (String) - Name of the extension to remove
303

304
**Returns:** `true` if the extension was removed, `false` if it wasn't found
305

306
```javascript
307
// Remove specific extension
308
const removed = instance.removeExt('myExtension');
309
if (removed) {
310
  console.log('Extension removed successfully');
311
}
312

313
// Extension cleanup is handled automatically
314
```
315

316
## Method Chaining Examples
317

318
```javascript
319
// Chain multiple operations
320
instance
321
  .update(true)
322
  .scroll({ y: 0 }, 500)
323
  .options('scrollbars.autoHide', 'leave');
324

325
// Update options and scroll
326
instance
327
  .options({
328
    scrollbars: { autoHideDelay: 200 }
329
  })
330
  .sleep()
331
  .update()
332
  .scroll({ x: '50%', y: '50%' }, 1000, 'easeInOutQuad');
333

334
// Extension management with chaining
335
instance
336
  .addExt('customExtension', { option: true })
337
  .update()
338
  .scroll({ y: 100 });
339
```
340

341
## Types
342

343
```javascript { .api }
344
type ScrollCoordinates = {
345
  x?: number | string;
346
  y?: number | string;
347
} | number | string | Element;
348

349
interface ScrollPositionInfo {
350
  position: { x: number; y: number };
351
  ratio: { x: number; y: number };
352
  max: { x: number; y: number };
353
}
354

355
interface ScrollPosition {
356
  x: number;
357
  y: number;
358
}
359

360
type EasingFunction = (t: number, b: number, c: number, d: number) => number;
361

362
interface OverlayScrollbarsState {
363
  destroyed: boolean;
364
  sleeping: boolean;
365
  autoUpdate: boolean | null;
366
  widthAuto: boolean;
367
  heightAuto: boolean;
368
  padding: { t: number; r: number; b: number; l: number };
369
  overflowAmount: { x: number; y: number };
370
  hideOverflow: { x: boolean; y: boolean };
371
  hasOverflow: { x: boolean; y: boolean };
372
  contentScrollSize: { width: number; height: number };
373
  viewportSize: { width: number; height: number };
374
  hostSize: { width: number; height: number };
375
}
376

377
interface OverlayScrollbarsElements {
378
  target: Element;
379
  host: Element;
380
  padding: Element;
381
  viewport: Element;
382
  content: Element;
383
  scrollbarHorizontal: {
384
    scrollbar: Element;
385
    track: Element;
386
    handle: Element;
387
  };
388
  scrollbarVertical: {
389
    scrollbar: Element;
390
    track: Element;
391
    handle: Element;
392
  };
393
  scrollbarCorner: Element;
394
}
395
```