0
# SimpleBar React
1

2
SimpleBar React is a React component wrapper for SimpleBar, a custom scrollbar library that replaces browser default scrollbars with CSS-styled ones while maintaining native scroll performance. The component provides a declarative React interface for implementing custom scrollbars, supporting both regular JSX children and render prop patterns for advanced use cases.
3

4
## Package Information
5

6
- **Package Name**: simplebar-react
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install simplebar-react`
10
- **Peer Dependencies**: React >=16.8.0
11

12
## Core Imports
13

14
```typescript
15
import SimpleBar from 'simplebar-react';
16
import 'simplebar-react/dist/simplebar.min.css';
17
```
18

19
For CommonJS:
20

21
```javascript
22
const SimpleBar = require('simplebar-react');
23
require('simplebar-react/dist/simplebar.min.css');
24
```
25

26
## Basic Usage
27

28
```typescript
29
import SimpleBar from 'simplebar-react';
30
import 'simplebar-react/dist/simplebar.min.css';
31

32
function App() {
33
  return (
34
    <SimpleBar style={{ maxHeight: 300 }}>
35
      <div>
36
        <p>Your scrollable content goes here...</p>
37
        <p>Multiple lines of content...</p>
38
        <p>That will show custom scrollbars when overflowing...</p>
39
      </div>
40
    </SimpleBar>
41
  );
42
}
43
```
44

45
## Capabilities
46

47
### SimpleBar Component
48

49
The main React component that wraps content with custom scrollbars while maintaining native scroll behavior.
50

51
```typescript { .api }
52
declare const SimpleBar: React.ForwardRefExoticComponent<
53
  Props & React.RefAttributes<SimpleBarCore | null>
54
> & {
55
  displayName: 'SimpleBar';
56
};
57

58
interface Props extends 
59
  Omit<React.HTMLAttributes<HTMLDivElement>, 'children'>,
60
  SimpleBarOptions {
61
  children?: React.ReactNode | RenderFunc;
62
  scrollableNodeProps?: {
63
    ref?: any;
64
    className?: string;
65
    [key: string]: any;
66
  };
67
}
68
```
69

70
**Usage Examples:**
71

72
```typescript
73
// Basic usage
74
<SimpleBar style={{ maxHeight: 400 }}>
75
  <YourContent />
76
</SimpleBar>
77

78
// With options
79
<SimpleBar 
80
  forceVisible="y" 
81
  autoHide={false} 
82
  scrollbarMinSize={30}
83
>
84
  <YourContent />
85
</SimpleBar>
86

87
// With scrollableNodeProps
88
<SimpleBar 
89
  scrollableNodeProps={{ 
90
    ref: scrollableRef,
91
    className: 'custom-scrollable',
92
    'data-testid': 'scrollable-area'
93
  }}
94
>
95
  <YourContent />
96
</SimpleBar>
97
```
98

99
### Render Function Pattern
100

101
Advanced usage pattern that provides access to internal DOM elements and their props.
102

103
```typescript { .api }
104
type RenderFunc = (props: {
105
  scrollableNodeRef: React.MutableRefObject<HTMLElement | undefined>;
106
  scrollableNodeProps: {
107
    className: string;
108
    ref: React.MutableRefObject<HTMLElement | undefined>;
109
    tabIndex: number;
110
    role: string;
111
    'aria-label': string;
112
  };
113
  contentNodeRef: React.MutableRefObject<HTMLElement | undefined>;
114
  contentNodeProps: {
115
    className: string;
116
    ref: React.MutableRefObject<HTMLElement | undefined>;
117
  };
118
}) => React.ReactNode;
119
```
120

121
**Usage Example:**
122

123
```typescript
124
<SimpleBar>
125
  {({ scrollableNodeProps, contentNodeProps }) => (
126
    <div {...scrollableNodeProps}>
127
      <div {...contentNodeProps}>
128
        <YourContent />
129
      </div>
130
    </div>
131
  )}
132
</SimpleBar>
133
```
134

135
### Component Ref Access
136

137
Access to the underlying SimpleBar core instance for imperative operations.
138

139
```typescript { .api }
140
// Ref type
141
type SimpleBarRef = SimpleBarCore | null;
142

143
// Core instance methods (from simplebar-core)
144
interface SimpleBarCore {
145
  /** Recalculate scrollbar positions and visibility */
146
  recalculate(): void;
147
  
148
  /** Get the content element */
149
  getContentElement(): HTMLElement | null;
150
  
151
  /** Get the scrollable wrapper element */
152
  getScrollElement(): HTMLElement | null;
153
  
154
  /** Clean up and remove all event listeners */
155
  unMount(): void;
156
  
157
  /** Root element that SimpleBar was applied to */
158
  el: HTMLElement;
159
}
160
```
161

162
**Usage Example:**
163

164
```typescript
165
import { useRef, useEffect } from 'react';
166
import SimpleBar from 'simplebar-react';
167

168
function MyComponent() {
169
  const simpleBarRef = useRef<SimpleBarCore | null>(null);
170

171
  useEffect(() => {
172
    // Recalculate after content changes
173
    simpleBarRef.current?.recalculate();
174
  }, [someData]);
175

176
  const scrollToBottom = () => {
177
    const scrollElement = simpleBarRef.current?.getScrollElement();
178
    if (scrollElement) {
179
      scrollElement.scrollTop = scrollElement.scrollHeight;
180
    }
181
  };
182

183
  return (
184
    <SimpleBar ref={simpleBarRef}>
185
      <YourContent />
186
    </SimpleBar>
187
  );
188
}
189
```
190

191
## SimpleBar Options
192

193
Configuration options inherited from simplebar-core that control scrollbar behavior and appearance.
194

195
```typescript { .api }
196
interface SimpleBarOptions {
197
  /** Force scrollbar visibility: true (both), false (auto), 'x' (horizontal), 'y' (vertical) */
198
  forceVisible?: boolean | 'x' | 'y';
199
  
200
  /** Enable clicking on track to scroll (default: true) */
201
  clickOnTrack?: boolean;
202
  
203
  /** Minimum scrollbar size in pixels (default: 25) */
204
  scrollbarMinSize?: number;
205
  
206
  /** Maximum scrollbar size in pixels (default: 0 - no limit) */
207
  scrollbarMaxSize?: number;
208
  
209
  /** Custom CSS class names for scrollbar elements */
210
  classNames?: Partial<ClassNames>;
211
  
212
  /** ARIA label for accessibility (default: "scrollable content") */
213
  ariaLabel?: string;
214
  
215
  /** Tab index for keyboard navigation (default: 0) */
216
  tabIndex?: number;
217
  
218
  /** Custom scrollable element (overrides default) */
219
  scrollableNode?: HTMLElement | null;
220
  
221
  /** Custom content element (overrides default) */
222
  contentNode?: HTMLElement | null;
223
  
224
  /** Auto-hide scrollbars when not in use (default: true) */
225
  autoHide?: boolean;
226
}
227
```
228

229
**Usage Examples:**
230

231
```typescript
232
// Force vertical scrollbar to always be visible
233
<SimpleBar forceVisible="y">
234
  <YourContent />
235
</SimpleBar>
236

237
// Disable auto-hiding and set custom scrollbar size
238
<SimpleBar 
239
  autoHide={false}
240
  scrollbarMinSize={30}
241
  scrollbarMaxSize={100}
242
>
243
  <YourContent />
244
</SimpleBar>
245

246
// Custom ARIA label and tab index for accessibility
247
<SimpleBar 
248
  ariaLabel="Chat messages"
249
  tabIndex={-1}
250
>
251
  <ChatMessages />
252
</SimpleBar>
253
```
254

255
## CSS Class Names
256

257
Customizable CSS class names for styling scrollbar elements.
258

259
```typescript { .api }
260
interface ClassNames {
261
  /** Content element class (default: 'simplebar-content') */
262
  contentEl: string;
263
  
264
  /** Content wrapper element class (default: 'simplebar-content-wrapper') */
265
  contentWrapper: string;
266
  
267
  /** Offset element class (default: 'simplebar-offset') */
268
  offset: string;
269
  
270
  /** Mask element class (default: 'simplebar-mask') */
271
  mask: string;
272
  
273
  /** Wrapper element class (default: 'simplebar-wrapper') */
274
  wrapper: string;
275
  
276
  /** Placeholder element class (default: 'simplebar-placeholder') */
277
  placeholder: string;
278
  
279
  /** Scrollbar handle class (default: 'simplebar-scrollbar') */
280
  scrollbar: string;
281
  
282
  /** Scrollbar track class (default: 'simplebar-track') */
283
  track: string;
284
  
285
  /** Height observer wrapper class (default: 'simplebar-height-auto-observer-wrapper') */
286
  heightAutoObserverWrapperEl: string;
287
  
288
  /** Height observer element class (default: 'simplebar-height-auto-observer') */
289
  heightAutoObserverEl: string;
290
  
291
  /** Visible state class (default: 'simplebar-visible') */
292
  visible: string;
293
  
294
  /** Horizontal orientation class (default: 'simplebar-horizontal') */
295
  horizontal: string;
296
  
297
  /** Vertical orientation class (default: 'simplebar-vertical') */
298
  vertical: string;
299
  
300
  /** Hover state class (default: 'simplebar-hover') */
301
  hover: string;
302
  
303
  /** Dragging state class (default: 'simplebar-dragging') */
304
  dragging: string;
305
  
306
  /** Scrolling state class (default: 'simplebar-scrolling') */
307
  scrolling: string;
308
  
309
  /** Scrollable state class (default: 'simplebar-scrollable') */
310
  scrollable: string;
311
  
312
  /** Mouse entered state class (default: 'simplebar-mouse-entered') */
313
  mouseEntered: string;
314
}
315
```
316

317
**Usage Example:**
318

319
```typescript
320
<SimpleBar 
321
  classNames={{
322
    wrapper: 'my-custom-wrapper',
323
    track: 'my-custom-track',
324
    scrollbar: 'my-custom-scrollbar'
325
  }}
326
>
327
  <YourContent />
328
</SimpleBar>
329
```
330

331
## Common Use Cases
332

333
### Chat Box with Auto-Scroll
334

335
```typescript
336
import { useRef, useEffect } from 'react';
337
import SimpleBar from 'simplebar-react';
338

339
function ChatBox({ messages }) {
340
  const scrollRef = useRef<SimpleBarCore | null>(null);
341

342
  useEffect(() => {
343
    // Auto-scroll to bottom when new messages arrive
344
    const scrollElement = scrollRef.current?.getScrollElement();
345
    if (scrollElement) {
346
      scrollElement.scrollTop = scrollElement.scrollHeight;
347
    }
348
  }, [messages]);
349

350
  return (
351
    <SimpleBar 
352
      ref={scrollRef}
353
      style={{ height: 400 }}
354
      autoHide={false}
355
    >
356
      {messages.map(message => (
357
        <div key={message.id}>{message.text}</div>
358
      ))}
359
    </SimpleBar>
360
  );
361
}
362
```
363

364
### Data Table with Custom Styling
365

366
```typescript
367
<SimpleBar 
368
  style={{ maxHeight: 500 }}
369
  classNames={{
370
    track: 'data-table-scrollbar-track',
371
    scrollbar: 'data-table-scrollbar-handle'
372
  }}
373
  scrollbarMinSize={40}
374
>
375
  <table>
376
    <thead>
377
      <tr>
378
        <th>Name</th>
379
        <th>Email</th>
380
        <th>Role</th>
381
      </tr>
382
    </thead>
383
    <tbody>
384
      {users.map(user => (
385
        <tr key={user.id}>
386
          <td>{user.name}</td>
387
          <td>{user.email}</td>
388
          <td>{user.role}</td>
389
        </tr>
390
      ))}
391
    </tbody>
392
  </table>
393
</SimpleBar>
394
```
395

396
### Integration with Third-Party Libraries
397

398
For advanced use cases like react-window, you can use the render prop pattern to access internal elements:
399

400
```typescript
401
import { FixedSizeList as List } from 'react-window';
402

403
<SimpleBar style={{ height: 400 }}>
404
  {({ scrollableNodeProps, contentNodeProps }) => (
405
    <div {...scrollableNodeProps}>
406
      <List
407
        height={400}
408
        itemCount={1000}
409
        itemSize={35}
410
      >
411
        {({ index, style }) => (
412
          <div style={style}>
413
            Item {index}
414
          </div>
415
        )}
416
      </List>
417
    </div>
418
  )}
419
</SimpleBar>
420
```