0
# Configuration & Styling
1

2
Comprehensive configuration options for scrollbar behavior, appearance, and accessibility features.
3

4
## Capabilities
5

6
### CSS Class Names Configuration
7

8
Customize the CSS class names used by SimpleBar components for styling integration.
9

10
```typescript { .api }
11
interface ClassNames {
12
  /** Content element containing the scrollable content */
13
  contentEl: string;
14
  
15
  /** Wrapper element for the content with native scrollbar hidden */
16
  contentWrapper: string;
17
  
18
  /** Offset element for hiding native scrollbar */
19
  offset: string;
20
  
21
  /** Mask element for clipping content */
22
  mask: string;
23
  
24
  /** Main wrapper element containing all SimpleBar components */
25
  wrapper: string;
26
  
27
  /** Placeholder element for maintaining layout dimensions */
28
  placeholder: string;
29
  
30
  /** Custom scrollbar handle element */
31
  scrollbar: string;
32
  
33
  /** Track element containing the scrollbar */
34
  track: string;
35
  
36
  /** Height auto-observer wrapper for dynamic content sizing */
37
  heightAutoObserverWrapperEl: string;
38
  
39
  /** Height auto-observer element */
40
  heightAutoObserverEl: string;
41
  
42
  /** Class applied when scrollbar is visible */
43
  visible: string;
44
  
45
  /** Class applied to horizontal scrollbar components */
46
  horizontal: string;
47
  
48
  /** Class applied to vertical scrollbar components */
49
  vertical: string;
50
  
51
  /** Class applied when hovering over scrollbar */
52
  hover: string;
53
  
54
  /** Class applied when dragging scrollbar */
55
  dragging: string;
56
  
57
  /** Class applied when scrolling is active */
58
  scrolling: string;
59
  
60
  /** Class applied when element is scrollable */
61
  scrollable: string;
62
  
63
  /** Class applied when mouse enters scrollable area */
64
  mouseEntered: string;
65
}
66
```
67

68
**Usage Examples:**
69

70
```typescript
71
import SimpleBar from "simplebar";
72

73
// Custom class names for theming
74
const simpleBar = new SimpleBar(element, {
75
  classNames: {
76
    scrollbar: 'my-custom-scrollbar',
77
    track: 'my-custom-track',
78
    visible: 'my-visible-state',
79
    hover: 'my-hover-state'
80
  }
81
});
82
```
83

84
### Default Configuration
85

86
Access and understand the default SimpleBar configuration options.
87

88
```typescript { .api }
89
/**
90
 * Default configuration options used when no custom options are provided
91
 */
92
static defaultOptions: {
93
  forceVisible: false,
94
  clickOnTrack: true,
95
  scrollbarMinSize: 25,
96
  scrollbarMaxSize: 0,
97
  ariaLabel: 'scrollable content',
98
  tabIndex: 0,
99
  classNames: ClassNames,
100
  scrollableNode: null,
101
  contentNode: null,
102
  autoHide: true
103
};
104
```
105

106
### Scrollbar Behavior Options
107

108
Configure scrollbar interaction and visibility behavior.
109

110
```typescript { .api }
111
interface BehaviorOptions {
112
  /** Force scrollbar visibility regardless of content overflow */
113
  forceVisible?: boolean | 'x' | 'y';
114
  
115
  /** Enable clicking on track area to scroll */
116
  clickOnTrack?: boolean;
117
  
118
  /** Automatically hide scrollbar when not actively scrolling */
119
  autoHide?: boolean;
120
}
121
```
122

123
**Usage Examples:**
124

125
```typescript
126
// Always show scrollbars
127
const simpleBar = new SimpleBar(element, {
128
  forceVisible: true,
129
  autoHide: false
130
});
131

132
// Show only vertical scrollbar, disable track clicking
133
const simpleBar = new SimpleBar(element, {
134
  forceVisible: 'y',
135
  clickOnTrack: false
136
});
137
```
138

139
### Scrollbar Sizing Options
140

141
Control the minimum and maximum size of scrollbar handles.
142

143
```typescript { .api }
144
interface SizingOptions {
145
  /** Minimum scrollbar handle size in pixels */
146
  scrollbarMinSize?: number;
147
  
148
  /** Maximum scrollbar handle size in pixels (0 = no limit) */
149
  scrollbarMaxSize?: number;
150
}
151
```
152

153
**Usage Examples:**
154

155
```typescript
156
// Large minimum scrollbar for touch interfaces
157
const simpleBar = new SimpleBar(element, {
158
  scrollbarMinSize: 40,
159
  scrollbarMaxSize: 200
160
});
161
```
162

163
### Accessibility Options
164

165
Configure accessibility features for screen readers and keyboard navigation.
166

167
```typescript { .api }
168
interface AccessibilityOptions {
169
  /** Aria label for screen readers */
170
  ariaLabel?: string;
171
  
172
  /** Tab index for keyboard navigation */
173
  tabIndex?: number;
174
}
175
```
176

177
**Usage Examples:**
178

179
```typescript
180
// Custom accessibility configuration
181
const simpleBar = new SimpleBar(element, {
182
  ariaLabel: 'Chat message history',
183
  tabIndex: 1
184
});
185
```
186

187
### Advanced DOM Options
188

189
Override default DOM element selection for advanced use cases.
190

191
```typescript { .api }
192
interface AdvancedOptions {
193
  /** Custom element to use as scrollable container */
194
  scrollableNode?: HTMLElement | null;
195
  
196
  /** Custom element containing the actual content */
197
  contentNode?: HTMLElement | null;
198
}
199
```
200

201
**Usage Examples:**
202

203
```typescript
204
// Use existing DOM structure
205
const scrollContainer = document.querySelector('.my-scroll-container');
206
const contentContainer = document.querySelector('.my-content');
207

208
const simpleBar = new SimpleBar(element, {
209
  scrollableNode: scrollContainer,
210
  contentNode: contentContainer
211
});
212
```
213

214
## CSS Styling
215

216
### Basic Scrollbar Styling
217

218
```css
219
/* Scrollbar track */
220
.simplebar-track {
221
  background: #f0f0f0;
222
  border-radius: 3px;
223
}
224

225
/* Scrollbar handle */
226
.simplebar-scrollbar::before {
227
  background: #888;
228
  border-radius: 3px;
229
  opacity: 0.7;
230
}
231

232
/* Hover states */
233
.simplebar-scrollbar.simplebar-hover::before {
234
  background: #555;
235
  opacity: 1;
236
}
237
```
238

239
### Custom Theme Example
240

241
```css
242
/* Dark theme scrollbar */
243
.dark-theme .simplebar-track {
244
  background: #2a2a2a;
245
}
246

247
.dark-theme .simplebar-scrollbar::before {
248
  background: #666;
249
}
250

251
.dark-theme .simplebar-scrollbar.simplebar-hover::before {
252
  background: #888;
253
}
254

255
/* Colored scrollbar */
256
.colored-scrollbar .simplebar-scrollbar::before {
257
  background: linear-gradient(to bottom, #4CAF50, #45a049);
258
}
259
```
260

261
### Animation Customization
262

263
```css
264
/* Custom show/hide animation */
265
.simplebar-scrollbar {
266
  transition: opacity 0.3s ease-in-out;
267
}
268

269
/* Custom scrollbar width */
270
.simplebar-track.simplebar-vertical {
271
  width: 8px;
272
}
273

274
.simplebar-track.simplebar-horizontal {
275
  height: 8px;
276
}
277
```
278

279
## Internal Helper Functions
280

281
SimpleBar includes several internal helper functions for scrollbar width detection and cross-browser compatibility:
282

283
```typescript { .api }
284
/**
285
 * Detect native scrollbar width
286
 * Cached value that updates on window resize/device pixel ratio changes
287
 * @returns Width of native scrollbar in pixels
288
 */
289
function scrollbarWidth(): number;
290
```
291

292
## RTL (Right-to-Left) Support
293

294
SimpleBar automatically detects and handles RTL layouts:
295

296
```html
297
<div dir="rtl" data-simplebar>
298
  <p>محتوى قابل للتمرير</p>
299
</div>
300
```
301

302
```css
303
/* RTL-specific styling if needed */
304
[dir="rtl"] .simplebar-track.simplebar-vertical {
305
  left: 0;
306
  right: auto;
307
}
308
```
309

310
### RTL Helper Functions
311

312
SimpleBar provides static methods for RTL compatibility:
313

314
```typescript { .api }
315
/**
316
 * Get RTL browser compatibility helpers
317
 * Tests browser behavior for RTL scrolling inconsistencies
318
 */
319
static getRtlHelpers(): {
320
  /** Determines if scrolling responds with negative values */
321
  isScrollOriginAtZero: boolean;
322
  /** Determines if origin scrollbar position is inverted */
323
  isScrollingToNegative: boolean;
324
} | null;
325
```