0
# Smooth Scrollbar
1

2
Smooth Scrollbar is a customizable, flexible, and high-performance scrollbar library for modern browsers that enables developers to replace native scrollbars with smooth-scrolling custom implementations. It offers extensive customization options through CSS styling, plugin system support, and comprehensive APIs for controlling scrolling behavior, momentum, and overscroll effects.
3

4
## Package Information
5

6
- **Package Name**: smooth-scrollbar
7
- **Package Type**: npm
8
- **Language**: TypeScript/JavaScript
9
- **Installation**: `npm install smooth-scrollbar`
10

11
## Core Imports
12

13
```typescript
14
import Scrollbar from "smooth-scrollbar";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const Scrollbar = require("smooth-scrollbar");
21
```
22

23
UMD (browser):
24

25
```html
26
<script src="dist/smooth-scrollbar.js"></script>
27
```
28

29
## Basic Usage
30

31
```typescript
32
import Scrollbar from "smooth-scrollbar";
33

34
// Initialize scrollbar on a DOM element
35
const container = document.querySelector("#my-scrollbar");
36
const scrollbar = Scrollbar.init(container, {
37
  damping: 0.1,
38
  thumbMinSize: 20,
39
  renderByPixels: true,
40
  alwaysShowTracks: false,
41
  continuousScrolling: true
42
});
43

44
// Initialize on all elements with data-scrollbar attribute
45
const scrollbars = Scrollbar.initAll();
46

47
// Listen to scroll events
48
scrollbar.addListener((status) => {
49
  console.log(`Scroll position: x=${status.offset.x}, y=${status.offset.y}`);
50
});
51

52
// Programmatic scrolling
53
scrollbar.scrollTo(0, 100, 300); // x, y, duration in ms
54
```
55

56
## Architecture
57

58
Smooth Scrollbar is built around several key components:
59

60
- **Main Scrollbar Class**: Core functionality with lifecycle management and event handling
61
- **Track System**: Visual scrollbar tracks and thumbs with automatic sizing and positioning
62
- **Options System**: Comprehensive configuration with validation decorators
63
- **Plugin Architecture**: Extensible plugin system with lifecycle hooks for custom functionality
64
- **Event Handling**: Touch, mouse, wheel, and keyboard event processing for smooth scrolling
65
- **Momentum Engine**: Physics-based momentum calculation for natural scrolling feel
66

67
## Capabilities
68

69
### Core Scrollbar Management
70

71
Primary interface for creating, managing, and destroying scrollbar instances. Provides both single-element and batch operations.
72

73
```typescript { .api }
74
class SmoothScrollbar {
75
  static version: string;
76
  static ScrollbarPlugin: typeof ScrollbarPlugin;
77
  
78
  static init(elem: HTMLElement, options?: Partial<ScrollbarOptions>): Scrollbar;
79
  static initAll(options?: Partial<ScrollbarOptions>): Scrollbar[];
80
  static has(elem: HTMLElement): boolean;
81
  static get(elem: HTMLElement): Scrollbar | undefined;
82
  static getAll(): Scrollbar[];
83
  static destroy(elem: HTMLElement): void;
84
  static destroyAll(): void;
85
  static use(...Plugins: (typeof ScrollbarPlugin)[]): void;
86
  static attachStyle(): void;
87
  static detachStyle(): void;
88
}
89
```
90

91
[Core Management](./core-management.md)
92

93
### Scrollbar Instance Control
94

95
Individual scrollbar instance methods for precise control over scrolling behavior, position, and state.
96

97
```typescript { .api }
98
interface Scrollbar {
99
  readonly containerEl: HTMLElement;
100
  readonly contentEl: HTMLElement;
101
  readonly options: ScrollbarOptions;
102
  readonly size: ScrollbarSize;
103
  readonly offset: Data2d;
104
  readonly limit: Data2d;
105
  scrollTop: number;
106
  scrollLeft: number;
107
  
108
  destroy(): void;
109
  update(): void;
110
  scrollTo(x?: number, y?: number, duration?: number, options?: Partial<ScrollToOptions>): void;
111
  setPosition(x?: number, y?: number, options?: Partial<SetPositionOptions>): void;
112
  scrollIntoView(elem: HTMLElement, options?: Partial<ScrollIntoViewOptions>): void;
113
  addListener(fn: ScrollListener): void;
114
  removeListener(fn: ScrollListener): void;
115
}
116
```
117

118
[Instance Control](./instance-control.md)
119

120
### Plugin System
121

122
Extensible plugin architecture for adding custom behaviors like overscroll effects, custom easing, or specialized scrolling modes.
123

124
```typescript { .api }
125
class ScrollbarPlugin {
126
  static pluginName: string;
127
  static defaultOptions: any;
128
  
129
  readonly scrollbar: Scrollbar;
130
  readonly options: any;
131
  readonly name: string;
132
  
133
  onInit(): void;
134
  onDestroy(): void;
135
  onUpdate(): void;
136
  onRender(remainMomentum: Data2d): void;
137
  transformDelta(delta: Data2d, evt: Event): Data2d;
138
}
139
```
140

141
[Plugin System](./plugin-system.md)
142

143
### Momentum and Physics
144

145
Advanced momentum control for natural scrolling physics with customizable easing and momentum manipulation.
146

147
```typescript { .api }
148
interface Scrollbar {
149
  addMomentum(x: number, y: number): void;
150
  setMomentum(x: number, y: number): void;
151
  addTransformableMomentum(
152
    x: number, 
153
    y: number, 
154
    fromEvent: Event, 
155
    callback?: AddTransformableMomentumCallback
156
  ): void;
157
}
158

159
interface AddTransformableMomentumCallback {
160
  (this: Scrollbar, willScroll: boolean): void;
161
}
162
```
163

164
[Momentum Control](./momentum-control.md)
165

166
## Configuration Types
167

168
```typescript { .api }
169
interface ScrollbarOptions {
170
  damping: number;
171
  thumbMinSize: number;
172
  renderByPixels: boolean;
173
  alwaysShowTracks: boolean;
174
  continuousScrolling: boolean;
175
  delegateTo: EventTarget | null;
176
  wheelEventTarget: EventTarget | null; // deprecated
177
  plugins: any;
178
}
179

180
interface Data2d {
181
  x: number;
182
  y: number;
183
}
184

185
interface ScrollbarSize {
186
  container: Metrics;
187
  content: Metrics;
188
}
189

190
interface Metrics {
191
  width: number;
192
  height: number;
193
}
194

195
interface ScrollStatus {
196
  offset: Data2d;
197
  limit: Data2d;
198
}
199

200
interface ScrollListener {
201
  (this: Scrollbar, status: ScrollStatus): void;
202
}
203

204
interface TrackController {
205
  readonly xAxis: ScrollbarTrack;
206
  readonly yAxis: ScrollbarTrack;
207
  update(): void;
208
  autoHideOnIdle(): void;
209
}
210

211
interface ScrollbarTrack {
212
  readonly element: HTMLElement;
213
  readonly thumb: ScrollbarThumb;
214
  show(): void;
215
  hide(): void;
216
  update(offset: number, containerSize: number, contentSize: number): void;
217
  attachTo(element: HTMLElement): void;
218
}
219

220
interface ScrollbarThumb {
221
  readonly element: HTMLElement;
222
  displaySize: number;
223
  realSize: number;
224
  offset: number;
225
  attachTo(track: HTMLElement): void;
226
  update(scrollOffset: number, containerSize: number, pageSize: number): void;
227
}
228
```