0
# Sortable
1

2
Sortable is a JavaScript library for reorderable drag-and-drop lists on modern browsers and touch devices. It provides smooth animations, multi-drag support, and framework-agnostic integration without requiring jQuery.
3

4
## Package Information
5

6
- **Package Name**: sortablejs
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install sortablejs`
10

11
## Core Imports
12

13
### Default Import (Full Build)
14

15
```javascript
16
import Sortable from "sortablejs";
17
```
18

19
For CommonJS:
20

21
```javascript
22
const Sortable = require("sortablejs");
23
```
24

25
### Modular Imports
26

27
**Core Build (without default plugins):**
28

29
```javascript
30
import Sortable from "sortablejs/modular/sortable.core.esm.js";
31
```
32

33
**Complete Build (with all plugins):**
34

35
```javascript
36
import Sortable from "sortablejs/modular/sortable.complete.esm.js";
37
```
38

39
**Default Build (with standard plugins):**
40

41
```javascript
42
import Sortable from "sortablejs/modular/sortable.esm.js";
43
```
44

45
### Plugin Cherry-picking
46

47
```javascript
48
// Import with specific plugins
49
import Sortable, { MultiDrag, AutoScroll, Swap } from "sortablejs";
50

51
// Mount plugins before use
52
Sortable.mount(new MultiDrag(), new AutoScroll(), new Swap());
53

54
// From core build
55
import Sortable, { AutoScroll } from "sortablejs/modular/sortable.core.esm.js";
56
Sortable.mount(new AutoScroll());
57
```
58

59
## Basic Usage
60

61
```javascript
62
import Sortable from "sortablejs";
63

64
// Create a sortable list
65
const el = document.getElementById('items');
66
const sortable = Sortable.create(el, {
67
  animation: 150,
68
  ghostClass: 'sortable-ghost',
69
  onEnd: function(evt) {
70
    console.log('Item moved from index', evt.oldIndex, 'to', evt.newIndex);
71
  }
72
});
73

74
// Get the current order
75
const order = sortable.toArray();
76

77
// Programmatically sort
78
sortable.sort(['item-1', 'item-3', 'item-2']);
79

80
// Cleanup
81
sortable.destroy();
82
```
83

84
## Architecture
85

86
Sortable is built around several key components that work together to provide comprehensive drag-and-drop functionality:
87

88
### Core Constructor System
89
- **Main `Sortable` Class**: Central controller that manages all drag-and-drop behavior and instance lifecycle
90
- **Static Methods**: Factory methods (`Sortable.create()`) and global utilities (`Sortable.get()`, `Sortable.mount()`)
91
- **Instance Management**: Each DOM element can have one Sortable instance stored via internal expando property
92

93
### Event System Architecture
94
- **Comprehensive Lifecycle**: 12+ events covering the complete drag cycle from selection to completion
95
- **Event Bubbling Control**: Configurable event bubbling and cancellation for custom behavior
96
- **Cross-List Communication**: Events automatically handle data flow between multiple connected lists
97

98
### Plugin Architecture
99
- **Modular Design**: Core functionality can be extended with plugins without modifying the base library
100
- **Plugin Manager**: Central system for mounting, initializing, and coordinating multiple plugins
101
- **Built-in Plugins**: MultiDrag, AutoScroll, Swap, and OnSpill plugins provide advanced functionality
102
- **Event Integration**: Plugins can inject custom event properties and lifecycle hooks
103

104
### Utility System
105
- **DOM Utilities**: Cross-browser DOM manipulation, event handling, and element querying
106
- **Performance Optimizations**: Throttling, async scheduling, and efficient animation systems
107
- **Framework Integration**: Utilities designed to work with React, Vue, Angular and other frameworks
108

109
### Cross-Browser Compatibility
110
- **HTML5 Drag and Drop**: Primary implementation using native browser APIs when available
111
- **Fallback Mode**: Custom touch/mouse handling for older browsers or when forced
112
- **Mobile Support**: Touch event handling optimized for iOS, Android, and modern mobile browsers
113
- **Browser Detection**: Intelligent feature detection for Safari, Chrome, Firefox, IE11+ compatibility
114

115
## Capabilities
116

117
### Core API
118

119
Main constructor, static methods, and instance methods for creating and managing sortable lists.
120

121
```javascript { .api }
122
function Sortable(el: HTMLElement, options?: SortableOptions): Sortable;
123
Sortable.create(el: HTMLElement, options?: SortableOptions): Sortable;
124
Sortable.get(element: HTMLElement): Sortable | undefined;
125
```
126

127
[Core API](./core-api.md)
128

129
### Configuration Options
130

131
Comprehensive configuration system with 25+ options for customizing drag behavior, visual feedback, and interaction patterns.
132

133
```javascript { .api }
134
interface SortableOptions {
135
  group?: string | GroupOptions;
136
  sort?: boolean;
137
  disabled?: boolean;
138
  animation?: number;
139
  handle?: string;
140
  draggable?: string;
141
  // ... 20+ additional options
142
}
143
```
144

145
[Configuration Options](./configuration.md)
146

147
### Event System
148

149
Rich event lifecycle with callbacks for drag start/end, list changes, and custom interactions.
150

151
```javascript { .api }
152
interface EventCallbacks {
153
  onStart?: (evt: SortableEvent) => void;
154
  onEnd?: (evt: SortableEvent) => void;
155
  onAdd?: (evt: SortableEvent) => void;
156
  onUpdate?: (evt: SortableEvent) => void;
157
  // ... 8+ additional events
158
}
159
```
160

161
[Events](./events.md)
162

163
### Plugin System
164

165
Extensible plugin architecture for advanced functionality like multi-drag, auto-scroll, and element swapping.
166

167
```javascript { .api }
168
Sortable.mount(...plugins: SortablePlugin[]): void;
169

170
// Available plugins
171
import { MultiDrag, AutoScroll, Swap, OnSpill } from "sortablejs";
172
```
173

174
[Plugins](./plugins.md)
175

176
### Utility Functions
177

178
Collection of DOM manipulation and helper functions for advanced integrations and custom implementations.
179

180
```javascript { .api }
181
interface SortableUtils {
182
  on(el: HTMLElement, event: string, fn: Function): void;
183
  off(el: HTMLElement, event: string, fn: Function): void;
184
  css(el: HTMLElement, prop: string, value?: string): string | void;
185
  find(ctx: HTMLElement, tagName: string, iterator?: Function): HTMLElement[];
186
  // ... 15+ additional utilities
187
}
188
```
189

190
[Utilities](./utilities.md)
191

192
## Types
193

194
```javascript { .api }
195
interface SortableEvent {
196
  to: HTMLElement;
197
  from: HTMLElement;
198
  item: HTMLElement;
199
  clone?: HTMLElement;
200
  oldIndex: number;
201
  newIndex: number;
202
  oldDraggableIndex: number;
203
  newDraggableIndex: number;
204
  pullMode?: string | boolean;
205
}
206

207
interface GroupOptions {
208
  name: string;
209
  pull?: boolean | string | string[] | ((to: Sortable, from: Sortable) => boolean);
210
  put?: boolean | string | string[] | ((to: Sortable, from: Sortable) => boolean);
211
  revertClone?: boolean;
212
}
213

214
class Sortable {
215
  constructor(el: HTMLElement, options?: SortableOptions);
216
  el: HTMLElement;
217
  options: SortableOptions;
218
  
219
  // Instance methods
220
  toArray(): string[];
221
  sort(order: string[], useAnimation?: boolean): void;
222
  save(): void;
223
  closest(el: HTMLElement, selector?: string): HTMLElement | null;
224
  option(name: string, value?: any): any;
225
  destroy(): void;
226
  handleEvent(evt: Event): void;
227
}
228
```