0
# Core API
1

2
Primary SimpleBar class providing programmatic scrollbar creation and management functionality.
3

4
## Capabilities
5

6
### SimpleBar Constructor
7

8
Creates a new SimpleBar instance on the specified HTML element.
9

10
```typescript { .api }
11
/**
12
 * Creates a new SimpleBar instance with custom scrollbars
13
 * @param element - The HTML element to apply SimpleBar to
14
 * @param options - Configuration options for scrollbar behavior
15
 */
16
constructor(element: HTMLElement, options?: SimpleBarOptions);
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import SimpleBar from "simplebar";
23

24
// Basic initialization
25
const simpleBar = new SimpleBar(document.getElementById('myDiv'));
26

27
// With configuration options
28
const simpleBar = new SimpleBar(document.getElementById('chatBox'), {
29
  autoHide: false,
30
  scrollbarMinSize: 25,
31
  clickOnTrack: true,
32
  classNames: {
33
    scrollbar: 'my-custom-scrollbar'
34
  }
35
});
36
```
37

38
### Get Scroll Element
39

40
Returns the scrollable element for attaching scroll event listeners.
41

42
```typescript { .api }
43
/**
44
 * Returns the element that contains the scrollable content
45
 * Use this element to attach scroll event listeners
46
 * @returns The scrollable HTML element or null if not initialized
47
 */
48
getScrollElement(): HTMLElement | null;
49
```
50

51
**Usage Examples:**
52

53
```typescript
54
const simpleBar = new SimpleBar(document.getElementById('myDiv'));
55
const scrollEl = simpleBar.getScrollElement();
56

57
if (scrollEl) {
58
  scrollEl.addEventListener('scroll', (e) => {
59
    console.log('Scroll position:', scrollEl.scrollTop);
60
  });
61
}
62
```
63

64
### Get Content Element
65

66
Returns the content element for dynamically adding or modifying content.
67

68
```typescript { .api }
69
/**
70
 * Returns the element that contains the actual content
71
 * Use this element to add or modify scrollable content
72
 * @returns The content HTML element or null if not initialized
73
 */
74
getContentElement(): HTMLElement | null;
75
```
76

77
**Usage Examples:**
78

79
```typescript
80
const simpleBar = new SimpleBar(document.getElementById('myDiv'));
81
const contentEl = simpleBar.getContentElement();
82

83
if (contentEl) {
84
  // Add new content
85
  const newItem = document.createElement('div');
86
  newItem.textContent = 'New scrollable item';
87
  contentEl.appendChild(newItem);
88
}
89
```
90

91
### Recalculate Scrollbars
92

93
Manually recalculates scrollbar dimensions when content changes dynamically.
94

95
```typescript { .api }
96
/**
97
 * Recalculates scrollbar size and position
98
 * Call this method when content dimensions change programmatically
99
 */
100
recalculate(): void;
101
```
102

103
**Usage Examples:**
104

105
```typescript
106
const simpleBar = new SimpleBar(document.getElementById('myDiv'));
107

108
// After adding content dynamically
109
const contentEl = simpleBar.getContentElement();
110
contentEl.innerHTML += '<div>New content that changes height</div>';
111

112
// Manually trigger recalculation
113
simpleBar.recalculate();
114
```
115

116
### Remove Event Listeners
117

118
Removes all event listeners without modifying DOM structure.
119

120
```typescript { .api }
121
/**
122
 * Remove all event listeners from DOM elements
123
 * Called automatically by unMount(), but can be called separately
124
 */
125
removeListeners(): void;
126
```
127

128
### Unmount Instance
129

130
Removes SimpleBar from the element and cleans up all event listeners.
131

132
```typescript { .api }
133
/**
134
 * Removes SimpleBar from the element and cleans up resources
135
 * Removes all event listeners and DOM modifications
136
 */
137
unMount(): void;
138
```
139

140
**Usage Examples:**
141

142
```typescript
143
const simpleBar = new SimpleBar(document.getElementById('myDiv'));
144

145
// Remove only event listeners (keep DOM structure)
146
simpleBar.removeListeners();
147

148
// Later, when fully cleaning up
149
simpleBar.unMount();
150
```
151

152
### Scrollbar Control Methods
153

154
Manual control of scrollbar visibility and positioning.
155

156
```typescript { .api }
157
/**
158
 * Show scrollbar for specified axis
159
 * @param axis - The axis ('x' or 'y') to show scrollbar for
160
 */
161
showScrollbar(axis?: Axis): void;
162

163
/**
164
 * Hide scrollbar for specified axis
165
 * @param axis - The axis ('x' or 'y') to hide scrollbar for  
166
 */
167
hideScrollbar(axis?: Axis): void;
168

169
/**
170
 * Position scrollbar handle for specified axis
171
 * @param axis - The axis ('x' or 'y') to position scrollbar for
172
 */
173
positionScrollbar(axis?: Axis): void;
174

175
/**
176
 * Toggle track visibility for specified axis
177
 * @param axis - The axis ('x' or 'y') to toggle track visibility for
178
 */
179
toggleTrackVisibility(axis?: Axis): void;
180

181
/**
182
 * Calculate scrollbar size for specified axis
183
 * @param axis - The axis ('x' or 'y') to calculate size for
184
 * @returns Scrollbar size in pixels
185
 */
186
getScrollbarSize(axis?: Axis): number;
187

188
/**
189
 * Get the width of the native browser scrollbar
190
 * @returns Width of native scrollbar in pixels
191
 */
192
getScrollbarWidth(): number;
193
```
194

195
**Usage Examples:**
196

197
```typescript
198
const simpleBar = new SimpleBar(document.getElementById('myDiv'));
199

200
// Manually show vertical scrollbar
201
simpleBar.showScrollbar('y');
202

203
// Hide horizontal scrollbar
204
simpleBar.hideScrollbar('x');
205

206
// Get current scrollbar size
207
const verticalScrollbarSize = simpleBar.getScrollbarSize('y');
208
console.log('Vertical scrollbar size:', verticalScrollbarSize);
209

210
// Get native browser scrollbar width
211
const nativeScrollbarWidth = simpleBar.getScrollbarWidth();
212
console.log('Native scrollbar width:', nativeScrollbarWidth);
213
```
214

215
### Advanced Methods
216

217
Lower-level methods for advanced use cases and debugging.
218

219
```typescript { .api }
220
/**
221
 * Hide native browser scrollbar
222
 * Internal method that positions content to hide native scrollbar
223
 */
224
hideNativeScrollbar(): void;
225

226
/**
227
 * Check if mouse position is within bounds of a rectangle
228
 * @param bbox - DOMRect to check bounds against
229
 * @returns True if mouse is within bounds
230
 */
231
isWithinBounds(bbox: DOMRect): boolean;
232

233
/**
234
 * Find child element matching query selector
235
 * @param el - Parent element to search within
236
 * @param query - CSS selector query
237
 * @returns First matching child element or undefined
238
 */
239
findChild(el: HTMLElement, query: string): HTMLElement | undefined;
240
```
241

242
### Static Helper Methods
243

244
Access to utility functions and browser compatibility helpers.
245

246
```typescript { .api }
247
/**
248
 * Get options from HTML data attributes
249
 * Used internally for data-attribute parsing
250
 */
251
static getOptions: (attributes: NamedNodeMap) => SimpleBarOptions;
252

253
/**
254
 * Helper functions for DOM manipulation and environment detection
255
 */
256
static helpers: {
257
  getElementWindow(element: Element): Window;
258
  getElementDocument(element: Element): Document;
259
  getOptions(attributes: NamedNodeMap): SimpleBarOptions;
260
  addClasses(el: HTMLElement | null, classes: string): void;
261
  removeClasses(el: HTMLElement | null, classes: string): void;
262
  classNamesToQuery(classNames: string): string;
263
  canUseDOM: boolean;
264
};
265

266
/**
267
 * Get RTL (right-to-left) browser compatibility helpers
268
 * @returns RTL configuration object or null if not supported
269
 */
270
static getRtlHelpers(): {
271
  isScrollOriginAtZero: boolean;
272
  isScrollingToNegative: boolean;
273
} | null;
274

275
/**
276
 * Get element offset position relative to document
277
 * @param el - Element to get offset for
278
 * @returns Object with top and left properties
279
 */
280
static getOffset(el: Element): { top: number; left: number };
281

282
/**
283
 * Default configuration options
284
 */
285
static defaultOptions: SimpleBarOptions;
286
```
287

288
## SimpleBar Options
289

290
```typescript { .api }
291
interface SimpleBarOptions {
292
  /** Force scrollbar visibility. true/false for both axes, 'x'/'y' for specific axis */
293
  forceVisible?: boolean | 'x' | 'y';
294
  
295
  /** Enable clicking on track to scroll (default: true) */
296
  clickOnTrack?: boolean;
297
  
298
  /** Minimum scrollbar size in pixels (default: 25) */
299
  scrollbarMinSize?: number;
300
  
301
  /** Maximum scrollbar size in pixels (default: 0 = no limit) */
302
  scrollbarMaxSize?: number;
303
  
304
  /** Custom CSS class names for scrollbar components */
305
  classNames?: Partial<ClassNames>;
306
  
307
  /** Accessibility label for screen readers (default: "scrollable content") */
308
  ariaLabel?: string;
309
  
310
  /** Tab index for keyboard navigation (default: 0) */
311
  tabIndex?: number;
312
  
313
  /** Custom scrollable element (advanced usage) */
314
  scrollableNode?: HTMLElement | null;
315
  
316
  /** Custom content element (advanced usage) */
317
  contentNode?: HTMLElement | null;
318
  
319
  /** Auto-hide scrollbar when not scrolling (default: true) */
320
  autoHide?: boolean;
321
}
322
```