0
# SimpleBar
1
2
SimpleBar is a JavaScript library that replaces browser default scrollbars with custom CSS-styled scrollbars while maintaining native scroll behavior and performance. It provides both automatic initialization via HTML attributes and manual instantiation for programmatic control.
3
4
This is the core vanilla JavaScript/TypeScript package from the SimpleBar monorepo, which also includes framework-specific variants for React, Vue, and Angular.
5
6
## Package Information
7
8
- **Package Name**: simplebar
9
- **Package Type**: npm
10
- **Language**: TypeScript/JavaScript
11
- **Installation**: `npm install simplebar`
12
13
## Core Imports
14
15
```typescript
16
import SimpleBar from "simplebar";
17
import "simplebar/dist/simplebar.css";
18
```
19
20
For CommonJS:
21
22
```javascript
23
const SimpleBar = require("simplebar");
24
require("simplebar/dist/simplebar.css");
25
```
26
27
For browser via CDN:
28
29
```html
30
<link rel="stylesheet" href="https://unpkg.com/simplebar@latest/dist/simplebar.css" />
31
<script src="https://unpkg.com/simplebar@latest/dist/simplebar.min.js"></script>
32
```
33
34
## Basic Usage
35
36
```typescript
37
import SimpleBar from "simplebar";
38
39
// Automatic initialization via HTML attribute
40
// <div data-simplebar>Content to be scrolled</div>
41
42
// Manual initialization
43
const scrollableEl = document.getElementById('myScrollableDiv');
44
const simpleBar = new SimpleBar(scrollableEl, {
45
autoHide: false,
46
scrollbarMinSize: 30
47
});
48
49
// Access the scrollable element for events
50
simpleBar.getScrollElement().addEventListener('scroll', () => {
51
console.log('Scrolled!');
52
});
53
```
54
55
## Architecture
56
57
SimpleBar is built around several key components:
58
59
- **SimpleBar Class**: Main API extending SimpleBarCore with DOM-specific functionality
60
- **SimpleBarCore**: Core scrollbar functionality with event handling and positioning
61
- **HTML API**: Automatic element detection and initialization via `data-simplebar` attributes
62
- **Instance Management**: Global tracking of SimpleBar instances via WeakMap
63
- **CSS Integration**: Custom scrollbar styling through CSS class overrides
64
65
## Capabilities
66
67
### Core API
68
69
Primary SimpleBar class with constructor, configuration options, and instance methods for creating and managing custom scrollbars.
70
71
```typescript { .api }
72
class SimpleBar extends SimpleBarCore {
73
constructor(element: HTMLElement, options?: SimpleBarOptions);
74
75
// Static properties from SimpleBarCore
76
static helpers: {
77
getElementWindow(element: Element): Window;
78
getElementDocument(element: Element): Document;
79
getOptions(attributes: NamedNodeMap): SimpleBarOptions;
80
addClasses(el: HTMLElement | null, classes: string): void;
81
removeClasses(el: HTMLElement | null, classes: string): void;
82
classNamesToQuery(classNames: string): string;
83
canUseDOM: boolean;
84
};
85
static getOptions: (attributes: NamedNodeMap) => SimpleBarOptions;
86
static defaultOptions: SimpleBarOptions;
87
static getRtlHelpers(): RtlHelpers | null;
88
static getOffset(el: Element): { top: number; left: number };
89
90
// Instance properties
91
el: HTMLElement;
92
options: SimpleBarOptions;
93
classNames: ClassNames;
94
axis: { x: AxisProps; y: AxisProps };
95
96
// Instance methods
97
getScrollElement(): HTMLElement | null;
98
getContentElement(): HTMLElement | null;
99
recalculate(): void;
100
unMount(): void;
101
}
102
103
interface SimpleBarOptions {
104
forceVisible?: boolean | 'x' | 'y';
105
clickOnTrack?: boolean;
106
scrollbarMinSize?: number;
107
scrollbarMaxSize?: number;
108
classNames?: Partial<ClassNames>;
109
ariaLabel?: string;
110
tabIndex?: number;
111
scrollableNode?: HTMLElement | null;
112
contentNode?: HTMLElement | null;
113
autoHide?: boolean;
114
}
115
```
116
117
[Core API](./core-api.md)
118
119
### HTML Automatic Initialization
120
121
Automatic scrollbar initialization using HTML data attributes and global DOM observation for dynamic content.
122
123
```typescript { .api }
124
// Static methods
125
static initDOMLoadedElements(): void;
126
static initHtmlApi(): void;
127
static removeObserver(): void;
128
static handleMutations(mutations: MutationRecord[]): void;
129
130
// Static properties
131
static instances: WeakMap<Node, SimpleBar>;
132
static globalObserver: MutationObserver;
133
```
134
135
[HTML API](./html-api.md)
136
137
### Configuration and Styling
138
139
Comprehensive configuration options for scrollbar behavior, appearance, and accessibility features.
140
141
```typescript { .api }
142
interface ClassNames {
143
contentEl: string;
144
contentWrapper: string;
145
offset: string;
146
mask: string;
147
wrapper: string;
148
placeholder: string;
149
scrollbar: string;
150
track: string;
151
heightAutoObserverWrapperEl: string;
152
heightAutoObserverEl: string;
153
visible: string;
154
horizontal: string;
155
vertical: string;
156
hover: string;
157
dragging: string;
158
scrolling: string;
159
scrollable: string;
160
mouseEntered: string;
161
}
162
```
163
164
[Configuration & Styling](./configuration.md)
165
166
## Types
167
168
```typescript { .api }
169
type Axis = 'x' | 'y';
170
171
interface AxisProps {
172
scrollOffsetAttr: 'scrollLeft' | 'scrollTop';
173
sizeAttr: 'width' | 'height';
174
scrollSizeAttr: 'scrollWidth' | 'scrollHeight';
175
offsetSizeAttr: 'offsetWidth' | 'offsetHeight';
176
offsetAttr: 'left' | 'top';
177
overflowAttr: 'overflowX' | 'overflowY';
178
dragOffset: number;
179
isOverflowing: boolean;
180
forceVisible: boolean;
181
track: {
182
size: number | null;
183
el: HTMLElement | null;
184
rect: DOMRect | null;
185
isVisible: boolean;
186
};
187
scrollbar: {
188
size: number | null;
189
el: HTMLElement | null;
190
rect: DOMRect | null;
191
isVisible: boolean;
192
};
193
}
194
195
interface RtlHelpers {
196
isScrollOriginAtZero: boolean;
197
isScrollingToNegative: boolean;
198
}
199
```