0
# Slider Creation
1

2
Core functionality for creating and initializing slider instances on DOM elements with comprehensive configuration options.
3

4
## Capabilities
5

6
### noUiSlider.create()
7

8
Creates a new slider instance on the specified DOM element.
9

10
```javascript { .api }
11
/**
12
 * Creates a new slider instance on the target element
13
 * @param target - DOM element to convert to slider
14
 * @param options - Configuration options for the slider
15
 * @returns Slider API object with methods and properties
16
 * @throws Error if target is invalid or already initialized
17
 */
18
noUiSlider.create(target: HTMLElement, options: SliderOptions): SliderAPI;
19
```
20

21
**Usage Examples:**
22

23
```javascript
24
import noUiSlider from "nouislider";
25

26
// Basic single-handle slider
27
const singleSlider = document.getElementById('single-slider');
28
noUiSlider.create(singleSlider, {
29
    start: 50,
30
    range: {
31
        'min': 0,
32
        'max': 100
33
    }
34
});
35

36
// Dual-handle range slider
37
const rangeSlider = document.getElementById('range-slider');
38
noUiSlider.create(rangeSlider, {
39
    start: [20, 80],
40
    connect: true,
41
    range: {
42
        'min': 0,
43
        'max': 100
44
    }
45
});
46

47
// Advanced slider with stepping and formatting
48
const advancedSlider = document.getElementById('advanced-slider');
49
noUiSlider.create(advancedSlider, {
50
    start: [1000, 3000],
51
    connect: true,
52
    step: 100,
53
    range: {
54
        'min': 0,
55
        'max': 5000
56
    },
57
    format: {
58
        to: function(value) {
59
            return '$' + Math.round(value);
60
        },
61
        from: function(value) {
62
            return Number(value.replace('$', ''));
63
        }
64
    }
65
});
66
```
67

68
## Configuration Options
69

70
### Required Options
71

72
#### start
73
Initial value(s) for the slider handles.
74

75
```javascript { .api }
76
start: number | number[];
77
```
78

79
- Single value: `start: 50`
80
- Multiple values: `start: [20, 80]`
81

82
#### range
83
Defines the minimum and maximum values, with optional stepping.
84

85
```javascript { .api }
86
range: RangeConfig;
87

88
interface RangeConfig {
89
    min: number | [number, number];  // Minimum value, optionally with step
90
    max: number | [number, number];  // Maximum value, optionally with step
91
    [position: string]: number | [number, number];  // Intermediate positions
92
}
93
```
94

95
**Examples:**
96

97
```javascript
98
// Basic linear range
99
range: {
100
    'min': 0,
101
    'max': 100
102
}
103

104
// Range with stepping
105
range: {
106
    'min': [0, 10],      // Min value 0, step size 10
107
    '50%': [500, 50],    // At 50% position, value 500, step size 50
108
    'max': 1000
109
}
110

111
// Non-linear range
112
range: {
113
    'min': 0,
114
    '10%': 50,
115
    '50%': 500,
116
    'max': 2000
117
}
118
```
119

120
### Connection Options
121

122
#### connect
123
Controls visual connection between handles.
124

125
```javascript { .api }
126
connect?: boolean | string | boolean[];
127
```
128

129
- `false`: No connections
130
- `true`: Connect all handles  
131
- `'lower'`: Connect from start to first handle
132
- `'upper'`: Connect from last handle to end
133
- Array: `[false, true, false]` - Connect specific segments
134

135
### Layout Options
136

137
#### direction
138
Text direction affecting slider orientation.
139

140
```javascript { .api }
141
direction?: 'ltr' | 'rtl';  // Default: 'ltr'
142
```
143

144
#### orientation
145
Physical orientation of the slider.
146

147
```javascript { .api }
148
orientation?: 'horizontal' | 'vertical';  // Default: 'horizontal'
149
```
150

151
### Interaction Options
152

153
#### behaviour
154
Defines interaction behaviors as space-separated string.
155

156
```javascript { .api }
157
behaviour?: string;  // Default: 'tap'
158
```
159

160
Available behaviors:
161
- `'tap'`: Click to move handles
162
- `'drag'`: Drag handles and ranges  
163
- `'fixed'`: Fixed distance between handles
164
- `'snap'`: Snap to step values
165
- `'hover'`: Fire hover events
166
- `'unconstrained'`: Allow handles to cross
167

168
**Examples:**
169

170
```javascript
171
behaviour: 'tap'                    // Click only
172
behaviour: 'tap-drag'              // Click and drag
173
behaviour: 'tap-drag-fixed'        // Fixed distance dragging
174
behaviour: 'unconstrained-tap'     // Handles can cross
175
```
176

177
### Value Constraints
178

179
#### step
180
Step size for value increments.
181

182
```javascript { .api }
183
step?: number;
184
```
185

186
#### margin
187
Minimum distance between handles.
188

189
```javascript { .api }
190
margin?: number;
191
```
192

193
#### limit
194
Maximum distance between handles.
195

196
```javascript { .api }
197
limit?: number;
198
```
199

200
#### padding
201
Padding from slider edges.
202

203
```javascript { .api }
204
padding?: number | number[];  // Single value or [start, end]
205
```
206

207
#### snap
208
Force values to snap to steps.
209

210
```javascript { .api }
211
snap?: boolean;  // Default: false
212
```
213

214
### Animation Options
215

216
#### animate
217
Enable smooth animations.
218

219
```javascript { .api }
220
animate?: boolean;  // Default: true
221
```
222

223
#### animationDuration
224
Animation duration in milliseconds.
225

226
```javascript { .api }
227
animationDuration?: number;  // Default: 300
228
```
229

230
### Formatting Options
231

232
#### format
233
Value formatting for display.
234

235
```javascript { .api }
236
format?: Formatter;
237

238
interface Formatter {
239
    to(value: number): string;    // Format for display
240
    from(value: string): number;  // Parse from string
241
}
242
```
243

244
#### ariaFormat
245
Accessibility formatting (defaults to format if not provided).
246

247
```javascript { .api }
248
ariaFormat?: Formatter;
249
```
250

251
**Example:**
252

253
```javascript
254
format: {
255
    to: function(value) {
256
        return value.toFixed(2) + '%';
257
    },
258
    from: function(value) {
259
        return parseFloat(value.replace('%', ''));
260
    }
261
}
262
```
263

264
### UI Enhancement Options
265

266
#### tooltips
267
Enable and configure tooltips.
268

269
```javascript { .api }
270
tooltips?: boolean | Formatter | (boolean | Formatter)[];
271
```
272

273
- `true`: Enable default tooltips
274
- `false`: Disable tooltips
275
- Formatter: Custom tooltip formatting
276
- Array: Per-handle configuration
277

278
#### pips
279
Scale markers configuration.
280

281
```javascript { .api }
282
pips?: PipsConfig;
283

284
interface PipsConfig {
285
    mode: 'range' | 'steps' | 'positions' | 'count' | 'values';
286
    values?: number[];
287
    stepped?: boolean;
288
    density?: number;
289
    filter?: (value: number, type: number) => number;
290
    format?: Formatter;
291
}
292
```
293

294
### Accessibility Options
295

296
#### keyboardSupport
297
Enable keyboard navigation.
298

299
```javascript { .api }
300
keyboardSupport?: boolean;  // Default: true
301
```
302

303
#### keyboardPageMultiplier
304
Multiplier for page up/down keys.
305

306
```javascript { .api }
307
keyboardPageMultiplier?: number;  // Default: 5
308
```
309

310
#### keyboardDefaultStep
311
Default step percentage for keyboard navigation.
312

313
```javascript { .api }
314
keyboardDefaultStep?: number;  // Default: 10
315
```
316

317
### Styling Options
318

319
#### cssPrefix
320
CSS class prefix for all elements.
321

322
```javascript { .api }
323
cssPrefix?: string | false;  // Default: 'noUi-'
324
```
325

326
#### cssClasses
327
Custom CSS class names.
328

329
```javascript { .api }
330
cssClasses?: CSSClasses;
331
```
332

333
#### documentElement
334
Custom document element for event handling.
335

336
```javascript { .api }
337
documentElement?: HTMLElement;
338
```
339

340
## Slider Lifecycle Management
341

342
### destroy()
343

344
Removes all slider functionality and cleans up DOM elements.
345

346
```javascript { .api }
347
/**
348
 * Destroy the slider instance and clean up
349
 * @returns void
350
 */
351
slider.noUiSlider.destroy(): void;
352
```
353

354
**Usage Examples:**
355

356
```javascript
357
// Clean up slider before removing element
358
const slider = document.getElementById('my-slider');
359
noUiSlider.create(slider, options);
360

361
// Later, when no longer needed
362
slider.noUiSlider.destroy();
363

364
// Now the element can be safely removed or reused
365
slider.remove();
366

367
// Or create a new slider on the same element
368
noUiSlider.create(slider, newOptions);
369
```
370

371
**What destroy() does:**
372

373
- Removes all event listeners
374
- Cleans up DOM structure created by noUiSlider
375
- Removes the `noUiSlider` property from the target element
376
- Frees up memory used by the slider instance
377

378
## Error Handling
379

380
The `create` method throws errors for invalid configurations:
381

382
```javascript
383
// Invalid target
384
noUiSlider.create(null, options);  // Error: create requires a single element
385

386
// Already initialized
387
noUiSlider.create(element, options);  // First call succeeds
388
noUiSlider.create(element, options);  // Error: Slider was already initialized
389

390
// Invalid range
391
noUiSlider.create(element, {
392
    start: 50,
393
    range: { min: 100, max: 0 }  // Error: Invalid range configuration
394
});
395
```
396

397
## Browser Support
398

399
- All modern browsers
400
- Internet Explorer > 9
401
- Touch devices (iOS, Android, Windows)
402
- Keyboard navigation support
403
- Screen reader compatibility