0
# noUiSlider
1
2
noUiSlider is a lightweight JavaScript range slider library with no dependencies. It provides highly customizable, accessible, and touch-enabled slider controls for web applications with support for single values, ranges, stepped values, and custom formatting.
3
4
## Package Information
5
6
- **Package Name**: nouislider
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install nouislider`
10
11
## Core Imports
12
13
ES6 modules:
14
15
```javascript
16
import noUiSlider from "nouislider";
17
import "nouislider/distribute/nouislider.min.css";
18
```
19
20
CommonJS:
21
22
```javascript
23
const noUiSlider = require("nouislider");
24
// CSS must be included separately in HTML: <link rel="stylesheet" href="node_modules/nouislider/distribute/nouislider.min.css">
25
```
26
27
Browser globals:
28
29
```html
30
<link rel="stylesheet" href="path/to/nouislider.css">
31
<script src="path/to/nouislider.js"></script>
32
<!-- noUiSlider is available as global variable -->
33
```
34
35
## Basic Usage
36
37
```javascript
38
import noUiSlider from "nouislider";
39
40
// Get a reference to a DOM element
41
const slider = document.getElementById('slider');
42
43
// Create a slider with basic configuration
44
noUiSlider.create(slider, {
45
start: [20, 80], // Initial values
46
connect: true, // Connect the handles with a colored bar
47
range: { // Value range
48
'min': 0,
49
'max': 100
50
}
51
});
52
53
// Get current values
54
const values = slider.noUiSlider.get();
55
console.log(values); // ['20.00', '80.00']
56
57
// Set new values
58
slider.noUiSlider.set([30, 70]);
59
60
// Listen for changes
61
slider.noUiSlider.on('update', function (values, handle) {
62
console.log('Handle', handle, 'updated to:', values[handle]);
63
});
64
```
65
66
## Architecture
67
68
noUiSlider is built around several key components:
69
70
- **Core Factory**: The `noUiSlider.create()` method that initializes sliders on DOM elements
71
- **Slider Instance API**: Methods and properties available on created slider instances
72
- **Range System**: Flexible value ranges with support for linear and non-linear scales
73
- **Event System**: Comprehensive event handling for user interactions and programmatic changes
74
- **Styling System**: CSS-based theming with customizable class names and structure
75
- **Accessibility**: Full ARIA support and keyboard navigation
76
77
## Capabilities
78
79
### Slider Creation
80
81
Core functionality for creating and initializing slider instances on DOM elements.
82
83
```javascript { .api }
84
noUiSlider.create(target: HTMLElement, options: SliderOptions): SliderAPI;
85
86
interface SliderOptions {
87
start: number | number[];
88
range: RangeConfig;
89
connect?: boolean | string | boolean[];
90
direction?: 'ltr' | 'rtl';
91
orientation?: 'horizontal' | 'vertical';
92
behaviour?: string;
93
step?: number;
94
margin?: number;
95
limit?: number;
96
padding?: number | number[];
97
snap?: boolean;
98
animate?: boolean;
99
animationDuration?: number;
100
format?: Formatter;
101
ariaFormat?: Formatter;
102
tooltips?: boolean | Formatter | (boolean | Formatter)[];
103
pips?: PipsConfig;
104
keyboardSupport?: boolean;
105
keyboardPageMultiplier?: number;
106
keyboardDefaultStep?: number;
107
cssPrefix?: string | false;
108
cssClasses?: CSSClasses;
109
documentElement?: HTMLElement;
110
}
111
```
112
113
[Slider Creation](./slider-creation.md)
114
115
### Value Management
116
117
Methods for getting and setting slider values programmatically.
118
119
```javascript { .api }
120
// Get current values
121
slider.noUiSlider.get(): string | string[];
122
123
// Set all values
124
slider.noUiSlider.set(values: number | number[], fireSetEvent?: boolean, exactInput?: boolean): void;
125
126
// Set specific handle value
127
slider.noUiSlider.setHandle(handleNumber: number, value: number, fireSetEvent?: boolean, exactInput?: boolean): void;
128
129
// Reset to initial values
130
slider.noUiSlider.reset(fireSetEvent?: boolean): void;
131
```
132
133
[Value Management](./value-management.md)
134
135
### Event Handling
136
137
Comprehensive event system for responding to slider interactions and value changes.
138
139
```javascript { .api }
140
// Bind event listener
141
slider.noUiSlider.on(eventName: string, callback: EventCallback): void;
142
143
// Remove event listener
144
slider.noUiSlider.off(eventName: string): void;
145
146
type EventCallback = (
147
values: string[],
148
handle: number,
149
unencoded: number[],
150
tap?: boolean,
151
positions?: number[],
152
slider?: SliderAPI
153
) => void;
154
```
155
156
[Event Handling](./event-handling.md)
157
158
### Configuration Updates
159
160
Runtime configuration updates and slider reconfiguration.
161
162
```javascript { .api }
163
slider.noUiSlider.updateOptions(
164
optionsToUpdate: Partial<SliderOptions>,
165
fireSetEvent?: boolean
166
): void;
167
168
// Get current configuration
169
slider.noUiSlider.options: SliderOptions;
170
```
171
172
[Configuration Updates](./configuration-updates.md)
173
174
### UI Enhancements
175
176
Additional UI features including tooltips, scale markers (pips), and styling customization.
177
178
```javascript { .api }
179
// Pips (scale markers)
180
slider.noUiSlider.pips(config: PipsConfig): HTMLElement;
181
slider.noUiSlider.removePips(): void;
182
183
// Tooltips
184
slider.noUiSlider.removeTooltips(): void;
185
slider.noUiSlider.getTooltips(): HTMLElement[];
186
187
// Handle elements
188
slider.noUiSlider.getOrigins(): HTMLElement[];
189
```
190
191
[UI Enhancements](./ui-enhancements.md)
192
193
## Types
194
195
```javascript { .api }
196
interface RangeConfig {
197
min: number | [number, number];
198
max: number | [number, number];
199
[position: string]: number | [number, number];
200
}
201
202
interface Formatter {
203
to(value: number): string;
204
from(value: string): number;
205
}
206
207
interface PipsConfig {
208
mode: 'range' | 'steps' | 'positions' | 'count' | 'values';
209
values?: number[];
210
stepped?: boolean;
211
density?: number;
212
filter?: (value: number, type: number) => number;
213
format?: Formatter;
214
}
215
216
interface CSSClasses {
217
target?: string;
218
base?: string;
219
origin?: string;
220
handle?: string;
221
handleLower?: string;
222
handleUpper?: string;
223
touchArea?: string;
224
horizontal?: string;
225
vertical?: string;
226
background?: string;
227
connect?: string;
228
connects?: string;
229
ltr?: string;
230
rtl?: string;
231
textDirectionLtr?: string;
232
textDirectionRtl?: string;
233
draggable?: string;
234
drag?: string;
235
tap?: string;
236
active?: string;
237
tooltip?: string;
238
pips?: string;
239
pipsHorizontal?: string;
240
pipsVertical?: string;
241
marker?: string;
242
markerHorizontal?: string;
243
markerVertical?: string;
244
markerNormal?: string;
245
markerLarge?: string;
246
markerSub?: string;
247
value?: string;
248
valueHorizontal?: string;
249
valueVertical?: string;
250
valueNormal?: string;
251
valueLarge?: string;
252
valueSub?: string;
253
}
254
255
interface SliderAPI {
256
destroy(): void;
257
steps(): [number | null, number | null][];
258
on(event: string, callback: EventCallback): void;
259
off(event: string): void;
260
get(): string | string[];
261
set(values: number | number[], fireSetEvent?: boolean, exactInput?: boolean): void;
262
setHandle(handleNumber: number, value: number, fireSetEvent?: boolean, exactInput?: boolean): void;
263
reset(fireSetEvent?: boolean): void;
264
updateOptions(optionsToUpdate: Partial<SliderOptions>, fireSetEvent?: boolean): void;
265
target: HTMLElement;
266
options: SliderOptions;
267
removePips(): void;
268
removeTooltips(): void;
269
getTooltips(): HTMLElement[];
270
getOrigins(): HTMLElement[];
271
pips(config: PipsConfig): HTMLElement;
272
}
273
```