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
```