0
# Configuration Options
1
2
Comprehensive configuration system with 25+ options for customizing drag behavior, visual feedback, and interaction patterns.
3
4
## Capabilities
5
6
### Group Configuration
7
8
Control cross-list dragging and sharing of items between multiple sortable lists.
9
10
```javascript { .api }
11
/**
12
* Group configuration for cross-list dragging
13
*/
14
interface GroupOptions {
15
/** Group name for identifying related lists */
16
name: string;
17
/** Whether items can be pulled from this list */
18
pull?: boolean | string | string[] | ((to: Sortable, from: Sortable) => boolean);
19
/** Whether items can be put into this list */
20
put?: boolean | string | string[] | ((to: Sortable, from: Sortable) => boolean);
21
/** Whether to revert cloned items when dragging ends */
22
revertClone?: boolean;
23
}
24
25
/** Group option can be string (group name) or full configuration object */
26
group?: string | GroupOptions;
27
```
28
29
**Usage Examples:**
30
31
```javascript
32
// Simple group sharing
33
const list1 = Sortable.create(el1, { group: 'shared' });
34
const list2 = Sortable.create(el2, { group: 'shared' });
35
36
// Advanced group configuration
37
const sourceList = Sortable.create(sourceEl, {
38
group: {
39
name: 'shared',
40
pull: 'clone', // Clone items when pulling
41
put: false // Don't accept items from other lists
42
}
43
});
44
45
const targetList = Sortable.create(targetEl, {
46
group: {
47
name: 'shared',
48
pull: false, // Don't allow pulling from this list
49
put: true // Accept items from other lists
50
}
51
});
52
```
53
54
### Basic Behavior Options
55
56
Core options that control the fundamental sortable behavior.
57
58
```javascript { .api }
59
/** Enable/disable sorting within the list */
60
sort?: boolean; // default: true
61
62
/** Disable all drag operations */
63
disabled?: boolean; // default: false
64
65
/** Custom storage adapter for save/restore functionality */
66
store?: {
67
get: (sortable: Sortable) => string[];
68
set: (sortable: Sortable) => void;
69
} | null; // default: null
70
```
71
72
### Element Selectors
73
74
Define which elements can be dragged and how to identify them.
75
76
```javascript { .api }
77
/** CSS selector for drag handle elements within items */
78
handle?: string | null; // default: null
79
80
/** CSS selector for draggable items */
81
draggable?: string; // default: ">*" (">li" for ul/ol elements)
82
83
/** CSS selector for elements that should be ignored during drag */
84
ignore?: string; // default: "a, img"
85
86
/** Filter function or selector for non-draggable elements */
87
filter?: string | ((evt: Event, item: HTMLElement, sortable: Sortable) => boolean) | null; // default: null
88
89
/** Call preventDefault when filter matches */
90
preventOnFilter?: boolean; // default: true
91
```
92
93
**Usage Examples:**
94
95
```javascript
96
// Only allow dragging by handle
97
Sortable.create(el, {
98
handle: '.drag-handle',
99
draggable: '.sortable-item'
100
});
101
102
// Filter out certain elements
103
Sortable.create(el, {
104
filter: '.no-drag',
105
onFilter: (evt) => {
106
console.log('Attempted to drag filtered element');
107
}
108
});
109
110
// Custom filter function
111
Sortable.create(el, {
112
filter: (evt, item, sortable) => {
113
return item.classList.contains('locked');
114
}
115
});
116
```
117
118
### Visual Feedback Options
119
120
Control the visual appearance during drag operations.
121
122
```javascript { .api }
123
/** CSS class for the ghost placeholder element */
124
ghostClass?: string; // default: "sortable-ghost"
125
126
/** CSS class for the chosen/active element */
127
chosenClass?: string; // default: "sortable-chosen"
128
129
/** CSS class for the element being dragged */
130
dragClass?: string; // default: "sortable-drag"
131
```
132
133
### Animation Options
134
135
Configure animations and visual transitions.
136
137
```javascript { .api }
138
/** Animation duration in milliseconds (0 = no animation) */
139
animation?: number; // default: 0
140
141
/** CSS easing function for animations */
142
easing?: string | null; // default: null
143
```
144
145
**Usage Examples:**
146
147
```javascript
148
// Smooth animations with custom easing
149
Sortable.create(el, {
150
animation: 300,
151
easing: 'cubic-bezier(0.4, 0, 0.2, 1)',
152
ghostClass: 'ghost-style',
153
chosenClass: 'chosen-style'
154
});
155
```
156
157
### Swap Detection Options
158
159
Fine-tune when and how elements swap positions during dragging.
160
161
```javascript { .api }
162
/** Threshold percentage (0-1) for triggering element swaps */
163
swapThreshold?: number; // default: 1
164
165
/** Always use inverted swap zone */
166
invertSwap?: boolean; // default: false
167
168
/** Threshold for inverted swap zone */
169
invertedSwapThreshold?: number | null; // default: null (uses swapThreshold value)
170
171
/** Sort direction detection */
172
direction?: 'horizontal' | 'vertical' | ((evt: Event, target: HTMLElement, dragEl: HTMLElement) => string); // default: auto-detect function
173
```
174
175
### Data Transfer Options
176
177
Configure how data is handled during drag operations.
178
179
```javascript { .api }
180
/** HTML attribute used by toArray() method for item identification */
181
dataIdAttr?: string; // default: "data-id"
182
183
/** Function to set drag data on dataTransfer object */
184
setData?: (dataTransfer: DataTransfer, dragEl: HTMLElement) => void; // default: sets text content
185
```
186
187
### Interaction Timing Options
188
189
Control when and how drag operations start.
190
191
```javascript { .api }
192
/** Delay in milliseconds before drag starts */
193
delay?: number; // default: 0
194
195
/** Apply delay only on touch devices */
196
delayOnTouchOnly?: boolean; // default: false
197
198
/** Pixels to move before canceling delayed drag on touch devices */
199
touchStartThreshold?: number; // default: 1 (or devicePixelRatio)
200
```
201
202
**Usage Examples:**
203
204
```javascript
205
// Delay drag start to prevent accidental drags
206
Sortable.create(el, {
207
delay: 100,
208
delayOnTouchOnly: true, // Only delay on touch devices
209
touchStartThreshold: 5 // Allow 5px movement before canceling
210
});
211
```
212
213
### Fallback Mode Options
214
215
Configure behavior when HTML5 drag and drop is not available or forced off.
216
217
```javascript { .api }
218
/** Force fallback mode (ignore HTML5 drag and drop) */
219
forceFallback?: boolean; // default: false
220
221
/** CSS class for the fallback drag element */
222
fallbackClass?: string; // default: "sortable-fallback"
223
224
/** Append fallback element to document body */
225
fallbackOnBody?: boolean; // default: false
226
227
/** Mouse movement tolerance before drag starts in fallback mode */
228
fallbackTolerance?: number; // default: 0
229
230
/** Offset for fallback element positioning */
231
fallbackOffset?: { x: number; y: number }; // default: {x: 0, y: 0}
232
```
233
234
### Event Options
235
236
Control event bubbling and interaction patterns.
237
238
```javascript { .api }
239
/** Allow drop events to bubble up */
240
dropBubble?: boolean; // default: false
241
242
/** Allow dragover events to bubble up */
243
dragoverBubble?: boolean; // default: false
244
245
/** Use pointer events if available */
246
supportPointer?: boolean; // default: auto-detected
247
```
248
249
### Advanced Options
250
251
Specialized options for advanced use cases.
252
253
```javascript { .api }
254
/** Remove clone element when hidden rather than just hiding it */
255
removeCloneOnHide?: boolean; // default: true
256
257
/** Distance in pixels from empty sortable to insert drag element */
258
emptyInsertThreshold?: number; // default: 5
259
```
260
261
**Usage Examples:**
262
263
```javascript
264
// Configure clone behavior and empty insertion
265
Sortable.create(el, {
266
removeCloneOnHide: false, // Hide clone instead of removing from DOM
267
emptyInsertThreshold: 10 // Increase sensitivity for empty lists
268
});
269
270
// Useful for custom styling during drag
271
Sortable.create(el, {
272
removeCloneOnHide: false,
273
onClone: (evt) => {
274
// Style the clone since it remains in DOM when hidden
275
evt.clone.style.visibility = 'hidden';
276
evt.clone.style.opacity = '0.3';
277
}
278
});
279
```
280
281
## Complete Options Interface
282
283
```javascript { .api }
284
interface SortableOptions {
285
// Group and sharing
286
group?: string | GroupOptions;
287
288
// Basic behavior
289
sort?: boolean;
290
disabled?: boolean;
291
store?: { get: (sortable: Sortable) => string[]; set: (sortable: Sortable) => void; } | null;
292
293
// Element selection
294
handle?: string | null;
295
draggable?: string;
296
ignore?: string;
297
filter?: string | ((evt: Event, item: HTMLElement, sortable: Sortable) => boolean) | null;
298
preventOnFilter?: boolean;
299
300
// Visual feedback
301
ghostClass?: string;
302
chosenClass?: string;
303
dragClass?: string;
304
305
// Animation
306
animation?: number;
307
easing?: string | null;
308
309
// Swap detection
310
swapThreshold?: number;
311
invertSwap?: boolean;
312
invertedSwapThreshold?: number | null;
313
direction?: 'horizontal' | 'vertical' | ((evt: Event, target: HTMLElement, dragEl: HTMLElement) => string);
314
315
// Data transfer
316
dataIdAttr?: string;
317
setData?: (dataTransfer: DataTransfer, dragEl: HTMLElement) => void;
318
319
// Interaction timing
320
delay?: number;
321
delayOnTouchOnly?: boolean;
322
touchStartThreshold?: number;
323
324
// Fallback mode
325
forceFallback?: boolean;
326
fallbackClass?: string;
327
fallbackOnBody?: boolean;
328
fallbackTolerance?: number;
329
fallbackOffset?: { x: number; y: number };
330
331
// Events
332
dropBubble?: boolean;
333
dragoverBubble?: boolean;
334
supportPointer?: boolean;
335
336
// Advanced
337
removeCloneOnHide?: boolean;
338
emptyInsertThreshold?: number;
339
340
// Event callbacks (see events.md for details)
341
onChoose?: (evt: SortableEvent) => void;
342
onUnchoose?: (evt: SortableEvent) => void;
343
onStart?: (evt: SortableEvent) => void;
344
onEnd?: (evt: SortableEvent) => void;
345
onAdd?: (evt: SortableEvent) => void;
346
onUpdate?: (evt: SortableEvent) => void;
347
onSort?: (evt: SortableEvent) => void;
348
onRemove?: (evt: SortableEvent) => void;
349
onFilter?: (evt: SortableEvent) => void;
350
onMove?: (evt: SortableEvent, originalEvent: Event) => boolean | number | void;
351
onClone?: (evt: SortableEvent) => void;
352
onChange?: (evt: SortableEvent) => void;
353
}
354
```