0
# Core API
1

2
Core constructor, static methods, and instance methods for creating and managing sortable lists.
3

4
## Capabilities
5

6
### Constructor
7

8
Creates a new Sortable instance on the specified HTML element.
9

10
```javascript { .api }
11
/**
12
 * Creates a sortable drag-and-drop interface on an HTML element
13
 * @param el - HTMLElement to make sortable
14
 * @param options - Configuration options object
15
 */
16
function Sortable(el: HTMLElement, options?: SortableOptions): Sortable;
17
```
18

19
**Usage Examples:**
20

21
```javascript
22
import Sortable from "sortablejs";
23

24
// Basic sortable list
25
const sortable = new Sortable(document.getElementById('list'), {
26
  animation: 150,
27
  ghostClass: 'sortable-ghost'
28
});
29

30
// Sortable with advanced options
31
const advancedSortable = new Sortable(document.getElementById('items'), {
32
  group: 'shared',
33
  animation: 300,
34
  handle: '.drag-handle',
35
  filter: '.no-drag',
36
  onEnd: (evt) => console.log('Drag ended', evt)
37
});
38
```
39

40
### Static Methods
41

42
#### Sortable.create()
43

44
Static factory method to create a sortable instance (alternative to constructor).
45

46
```javascript { .api }
47
/**
48
 * Static factory method to create a sortable instance
49
 * @param el - HTMLElement to make sortable
50
 * @param options - Configuration options object
51
 * @returns New Sortable instance
52
 */
53
Sortable.create(el: HTMLElement, options?: SortableOptions): Sortable;
54
```
55

56
#### Sortable.get()
57

58
Retrieve the Sortable instance associated with an HTML element.
59

60
```javascript { .api }
61
/**
62
 * Get the Sortable instance associated with an element
63
 * @param element - Element to get the instance for
64
 * @returns Sortable instance or undefined if none exists
65
 */
66
Sortable.get(element: HTMLElement): Sortable | undefined;
67
```
68

69
#### Sortable.mount()
70

71
Register plugins with Sortable for extended functionality.
72

73
```javascript { .api }
74
/**
75
 * Mount plugins to extend Sortable functionality
76
 * @param plugins - One or more plugin objects to register
77
 */
78
Sortable.mount(...plugins: SortablePlugin[]): void;
79
```
80

81
**Usage Examples:**
82

83
```javascript
84
import Sortable, { MultiDrag, AutoScroll } from "sortablejs";
85

86
// Mount plugins before creating sortable instances
87
Sortable.mount(new MultiDrag(), new AutoScroll());
88

89
// Now create sortables with plugin support
90
const sortable = Sortable.create(el, {
91
  multiDrag: true,
92
  selectedClass: 'selected'
93
});
94
```
95

96
### Static Properties
97

98
#### Sortable.version
99

100
Current version of the Sortable library.
101

102
```javascript { .api }
103
Sortable.version: string;
104
```
105

106
#### Sortable.utils
107

108
Collection of utility functions for DOM manipulation and helper operations.
109

110
```javascript { .api }
111
Sortable.utils: SortableUtils;
112
```
113

114
#### Sortable.active
115

116
Reference to the currently active (dragging) Sortable instance.
117

118
```javascript { .api }
119
Sortable.active: Sortable | null;
120
```
121

122
#### Sortable.dragged
123

124
Reference to the element currently being dragged.
125

126
```javascript { .api }
127
Sortable.dragged: HTMLElement | null;
128
```
129

130
#### Sortable.ghost
131

132
Reference to the ghost placeholder element during drag operations.
133

134
```javascript { .api }
135
Sortable.ghost: HTMLElement | null;
136
```
137

138
#### Sortable.clone
139

140
Reference to the cloned element (when using clone mode).
141

142
```javascript { .api }
143
Sortable.clone: HTMLElement | null;
144
```
145

146
### Instance Methods
147

148
#### toArray()
149

150
Serializes the sortable items into an array of data-id values or indices.
151

152
```javascript { .api }
153
/**
154
 * Serialize the sortable's item order
155
 * @returns Array of data-id attribute values or generated indices
156
 */
157
toArray(): string[];
158
```
159

160
**Usage Examples:**
161

162
```javascript
163
// HTML with data-id attributes
164
// <ul id="list">
165
//   <li data-id="item-1">First</li>
166
//   <li data-id="item-2">Second</li> 
167
//   <li data-id="item-3">Third</li>
168
// </ul>
169

170
const sortable = Sortable.create(document.getElementById('list'));
171
const order = sortable.toArray(); // ['item-1', 'item-2', 'item-3']
172

173
// Save order for later restoration
174
localStorage.setItem('list-order', JSON.stringify(order));
175
```
176

177
#### sort()
178

179
Programmatically reorder the sortable items according to an array of IDs.
180

181
```javascript { .api }
182
/**
183
 * Reorder items according to an array
184
 * @param order - Array of item IDs in desired order
185
 * @param useAnimation - Whether to animate the reordering
186
 */
187
sort(order: string[], useAnimation?: boolean): void;
188
```
189

190
**Usage Examples:**
191

192
```javascript
193
const sortable = Sortable.create(document.getElementById('list'));
194

195
// Reorder items programmatically
196
sortable.sort(['item-3', 'item-1', 'item-2']);
197

198
// Reorder with animation
199
sortable.sort(['item-2', 'item-3', 'item-1'], true);
200

201
// Restore saved order
202
const savedOrder = JSON.parse(localStorage.getItem('list-order'));
203
if (savedOrder) {
204
  sortable.sort(savedOrder);
205
}
206
```
207

208
#### save()
209

210
Save the current item order using the configured store option.
211

212
```javascript { .api }
213
/**
214
 * Save the current sorting order using the store option
215
 */
216
save(): void;
217
```
218

219
#### closest()
220

221
Find the closest draggable ancestor element.
222

223
```javascript { .api }
224
/**
225
 * Find the closest draggable ancestor element
226
 * @param el - Starting element
227
 * @param selector - CSS selector (optional, defaults to options.draggable)
228
 * @returns Closest draggable element or null
229
 */
230
closest(el: HTMLElement, selector?: string): HTMLElement | null;
231
```
232

233
#### option()
234

235
Get or set a configuration option on the sortable instance.
236

237
```javascript { .api }
238
/**
239
 * Get or set a configuration option
240
 * @param name - Option name
241
 * @param value - Option value (omit to get current value)
242
 * @returns Current option value when getting
243
 */
244
option(name: string, value?: any): any;
245
```
246

247
**Usage Examples:**
248

249
```javascript
250
const sortable = Sortable.create(el);
251

252
// Get current animation duration
253
const currentAnimation = sortable.option('animation'); // 0
254

255
// Update animation duration
256
sortable.option('animation', 300);
257

258
// Disable the sortable
259
sortable.option('disabled', true);
260

261
// Enable it again
262
sortable.option('disabled', false);
263
```
264

265
#### destroy()
266

267
Clean up the sortable instance and remove all event listeners.
268

269
```javascript { .api }
270
/**
271
 * Destroy the sortable instance and cleanup event listeners
272
 */
273
destroy(): void;
274
```
275

276
**Usage Examples:**
277

278
```javascript
279
const sortable = Sortable.create(el);
280

281
// Later, when component unmounts or is no longer needed
282
sortable.destroy();
283

284
// The element is no longer sortable and all event listeners are removed
285
```
286

287
#### handleEvent()
288

289
Main event handler for drag and drop events (used internally).
290

291
```javascript { .api }
292
/**
293
 * Main event handler for drag and drop events
294
 * @param evt - DOM event object
295
 */
296
handleEvent(evt: Event): void;
297
```
298

299
## Types
300

301
```javascript { .api }
302
interface SortablePlugin {
303
  name: string;
304
  defaults?: object;
305
  eventOptions?: object;
306
  initializePlugin?: (sortable: Sortable) => void;
307
}
308

309
interface SortableUtils {
310
  on(el: HTMLElement, event: string, fn: Function): void;
311
  off(el: HTMLElement, event: string, fn: Function): void;
312
  css(el: HTMLElement, prop: string, value?: string): string | void;
313
  find(ctx: HTMLElement, tagName: string, iterator?: Function): HTMLElement[];
314
  is(el: HTMLElement, selector: string): boolean;
315
  extend(dst: object, ...src: object[]): object;
316
  throttle(fn: Function, ms: number): Function;
317
  closest(el: HTMLElement, selector: string, ctx?: HTMLElement): HTMLElement | null;
318
  toggleClass(el: HTMLElement, name: string, state?: boolean): void;
319
  clone(el: HTMLElement): HTMLElement;
320
  index(el: HTMLElement, selector?: string): number;
321
  nextTick(fn: Function): number;
322
  cancelNextTick(id: number): void;
323
  detectDirection(el: HTMLElement): string;
324
  getChild(el: HTMLElement, childNum: number, options?: object): HTMLElement;
325
  expando: string;
326
}
327
```