0
# Scrollbar Instance Control
1

2
Individual scrollbar instance methods for precise control over scrolling behavior, position, and state. Each scrollbar instance provides comprehensive access to scrolling operations and state management.
3

4
## Capabilities
5

6
### Scrollbar Properties
7

8
Core properties providing access to scrollbar state and DOM elements.
9

10
```typescript { .api }
11
interface Scrollbar {
12
  /** Parent scrollbar reference for nested scrollbars */
13
  readonly parent: Scrollbar | null;
14
  
15
  /** Container DOM element */
16
  readonly containerEl: HTMLElement;
17
  
18
  /** Content DOM element inside container */
19
  readonly contentEl: HTMLElement;
20
  
21
  /** Track controller managing visual scrollbar tracks */
22
  readonly track: TrackController;
23
  
24
  /** Current configuration options */
25
  readonly options: ScrollbarOptions;
26
  
27
  /** Bounding box information */
28
  bounding: ScrollbarBounding;
29
  
30
  /** Size metrics for container and content */
31
  size: ScrollbarSize;
32
  
33
  /** Current scroll offset position */
34
  offset: Data2d;
35
  
36
  /** Maximum scroll limits */
37
  limit: Data2d;
38
  
39
  /** Vertical scroll position (alias for offset.y) */
40
  scrollTop: number;
41
  
42
  /** Horizontal scroll position (alias for offset.x) */
43
  scrollLeft: number;
44
}
45
```
46

47
### Lifecycle Management
48

49
Methods for managing the scrollbar instance lifecycle.
50

51
```typescript { .api }
52
/**
53
 * Destroys the scrollbar instance and cleans up all resources
54
 */
55
destroy(): void;
56

57
/**
58
 * Updates scrollbar state and recalculates dimensions
59
 */
60
update(): void;
61
```
62

63
**Usage Examples:**
64

65
```typescript
66
// Force update after DOM changes
67
scrollbar.update();
68

69
// Clean up when element is removed
70
scrollbar.destroy();
71
```
72

73
### Size and Visibility
74

75
Methods for querying scrollbar dimensions and element visibility.
76

77
```typescript { .api }
78
/**
79
 * Gets current size metrics for container and content
80
 * @returns Size information including container and content dimensions
81
 */
82
getSize(): ScrollbarSize;
83

84
/**
85
 * Checks if an element is visible within the scrollable area
86
 * @param elem - DOM element to check visibility for
87
 * @returns True if element is currently visible
88
 */
89
isVisible(elem: HTMLElement): boolean;
90
```
91

92
**Usage Examples:**
93

94
```typescript
95
// Check if element needs scrolling
96
const targetElement = document.querySelector("#target");
97
if (!scrollbar.isVisible(targetElement)) {
98
  scrollbar.scrollIntoView(targetElement);
99
}
100

101
// Get current dimensions
102
const size = scrollbar.getSize();
103
console.log(`Container: ${size.container.width}x${size.container.height}`);
104
console.log(`Content: ${size.content.width}x${size.content.height}`);
105
```
106

107
### Scroll Positioning
108

109
Methods for controlling scroll position with various options and animations.
110

111
```typescript { .api }
112
/**
113
 * Scrolls to specified position with optional animation
114
 * @param x - Horizontal position (optional)
115
 * @param y - Vertical position (optional)  
116
 * @param duration - Animation duration in milliseconds (optional)
117
 * @param options - Additional scrolling options (optional)
118
 */
119
scrollTo(x?: number, y?: number, duration?: number, options?: Partial<ScrollToOptions>): void;
120

121
/**
122
 * Sets scroll position immediately without animation
123
 * @param x - Horizontal position (optional)
124
 * @param y - Vertical position (optional)
125
 * @param options - Position setting options (optional)
126
 */
127
setPosition(x?: number, y?: number, options?: Partial<SetPositionOptions>): void;
128

129
/**
130
 * Scrolls an element into view with alignment options
131
 * @param elem - DOM element to scroll into view
132
 * @param options - Scroll into view configuration (optional)
133
 */
134
scrollIntoView(elem: HTMLElement, options?: Partial<ScrollIntoViewOptions>): void;
135
```
136

137
**Usage Examples:**
138

139
```typescript
140
// Smooth scroll to top
141
scrollbar.scrollTo(0, 0, 800);
142

143
// Instant positioning
144
scrollbar.setPosition(100, 200);
145

146
// Scroll element into view
147
const element = document.querySelector("#section-3");
148
scrollbar.scrollIntoView(element, {
149
  alignToTop: true,
150
  offsetTop: 20
151
});
152

153
// Custom easing and callback
154
scrollbar.scrollTo(0, 500, 1000, {
155
  easing: (t) => t * t, // quadratic easing
156
  callback() {
157
    console.log("Scroll completed!");
158
  }
159
});
160
```
161

162
### Event Listeners
163

164
Methods for managing scroll event listeners.
165

166
```typescript { .api }
167
/**
168
 * Adds a scroll event listener
169
 * @param fn - Listener function to add
170
 */
171
addListener(fn: ScrollListener): void;
172

173
/**
174
 * Removes a scroll event listener
175
 * @param fn - Listener function to remove
176
 */
177
removeListener(fn: ScrollListener): void;
178
```
179

180
**Usage Examples:**
181

182
```typescript
183
// Add scroll listener
184
const handleScroll = (status) => {
185
  const { offset, limit } = status;
186
  const scrollPercent = {
187
    x: (offset.x / limit.x) * 100,
188
    y: (offset.y / limit.y) * 100
189
  };
190
  console.log(`Scroll progress: ${scrollPercent.y.toFixed(1)}%`);
191
};
192

193
scrollbar.addListener(handleScroll);
194

195
// Remove listener when done
196
scrollbar.removeListener(handleScroll);
197
```
198

199
### Plugin Management
200

201
Methods for managing plugin options on individual scrollbar instances.
202

203
```typescript { .api }
204
/**
205
 * Updates options for a specific plugin
206
 * @param pluginName - Name of the plugin to update
207
 * @param options - New options for the plugin
208
 */
209
updatePluginOptions(pluginName: string, options?: any): void;
210
```
211

212
**Usage Examples:**
213

214
```typescript
215
// Update overscroll plugin options
216
scrollbar.updatePluginOptions("overscroll", {
217
  effect: "glow",
218
  glowColor: "#ff6b6b",
219
  maxOverscroll: 200
220
});
221
```
222

223
## Configuration Types
224

225
```typescript { .api }
226
interface ScrollToOptions {
227
  /** Callback function called when scroll completes */
228
  callback: (this: Scrollbar) => void;
229
  
230
  /** Easing function for scroll animation */
231
  easing: (percent: number) => number;
232
}
233

234
interface SetPositionOptions {
235
  /** Skip calling scroll listeners during position change */
236
  withoutCallbacks: boolean;
237
}
238

239
interface ScrollIntoViewOptions {
240
  /** Align element to top of viewport */
241
  alignToTop: boolean;
242
  
243
  /** Only scroll if element is not already visible */
244
  onlyScrollIfNeeded: boolean;
245
  
246
  /** Additional top offset */
247
  offsetTop: number;
248
  
249
  /** Additional left offset */
250
  offsetLeft: number;
251
  
252
  /** Additional bottom offset */
253
  offsetBottom: number;
254
}
255

256
interface ScrollbarBounding {
257
  top: number;
258
  right: number;
259
  bottom: number;
260
  left: number;
261
}
262
```