0
# Shopify Draggable
1

2
Shopify Draggable is a comprehensive JavaScript drag-and-drop library built with TypeScript that offers complete control over drag-and-drop behavior through a flexible API. It abstracts native browser events (drag, mouse, touch, and force touch) into a unified interface and includes specialized modules: Sortable for reordering elements, Droppable for defining drop zones, and Swappable for element swapping.
3

4
## Package Information
5

6
- **Package Name**: @shopify/draggable
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @shopify/draggable`
10

11
## Core Imports
12

13
```typescript
14
import { Draggable, Sortable, Droppable, Swappable } from "@shopify/draggable";
15
```
16

17
Base classes and utilities:
18

19
```typescript
20
import { BaseEvent, BasePlugin, Sensors, Plugins } from "@shopify/draggable";
21
```
22

23
For CommonJS:
24

25
```javascript
26
const { Draggable, Sortable, Droppable, Swappable } = require("@shopify/draggable");
27
const { BaseEvent, BasePlugin, Sensors, Plugins } = require("@shopify/draggable");
28
```
29

30
ES modules (alternative imports):
31

32
```typescript
33
import Draggable from "@shopify/draggable/lib/draggable";
34
import Sortable from "@shopify/draggable/lib/sortable";
35
```
36

37
## Basic Usage
38

39
```typescript
40
import { Draggable } from "@shopify/draggable";
41

42
// Basic draggable setup
43
const draggable = new Draggable(document.querySelectorAll('.container'), {
44
  draggable: '.item'
45
});
46

47
// Listen to drag events
48
draggable.on('drag:start', (event) => {
49
  console.log('Started dragging:', event.source);
50
});
51

52
draggable.on('drag:stop', (event) => {
53
  console.log('Stopped dragging:', event.source);
54
});
55

56
// Cleanup when done
57
draggable.destroy();
58
```
59

60
## Architecture
61

62
Shopify Draggable is built around several key components:
63

64
- **Core Draggable**: Base class providing fundamental drag-and-drop functionality
65
- **Specialized Classes**: Sortable, Droppable, and Swappable extend Draggable for specific use cases
66
- **Event System**: Comprehensive event lifecycle with cancelable events and custom data
67
- **Sensor System**: Pluggable input handling for mouse, touch, and native drag events
68
- **Plugin Architecture**: Extensible system with built-in plugins for mirrors, scrolling, announcements, etc.
69
- **Type Safety**: Full TypeScript integration with generic event types and comprehensive interfaces
70

71
## Capabilities
72

73
### Core Draggable
74

75
Basic drag-and-drop functionality with container management, event handling, and plugin system. Provides the foundation for all other draggable types.
76

77
```typescript { .api }
78
class Draggable<TEventListType = DraggableEventNames> {
79
  constructor(containers: DraggableContainer, options?: DraggableOptions);
80
  destroy(): void;
81
  on<T extends TEventListType>(eventName: T, callback: (event: GetEventByEventName<T>) => void): this;
82
  off<T extends TEventListType>(eventName: T, callback: (event: GetEventByEventName<T>) => void): this;
83
  trigger(event: AbstractEvent): void;
84
  isDragging(): boolean;
85
}
86

87
type DraggableContainer = HTMLElement | HTMLElement[] | NodeList;
88
```
89

90
[Core Draggable](./core-draggable.md)
91

92
### Sortable Lists
93

94
Reorder elements within or between containers with automatic position tracking and smooth animations. Perfect for to-do lists, priority queues, and dashboard widgets.
95

96
```typescript { .api }
97
class Sortable<T = SortableEventNames> extends Draggable<T> {
98
  constructor(containers: DraggableContainer, options?: DraggableOptions);
99
  index(element: HTMLElement): number;
100
  getSortableElementsForContainer(container: HTMLElement): HTMLElement[];
101
}
102
```
103

104
[Sortable Lists](./sortable.md)
105

106
### Droppable Zones
107

108
Create designated drop zones where draggable elements can be placed. Includes visual feedback and validation for valid/invalid drop targets.
109

110
```typescript { .api }
111
class Droppable<T = DroppableEventNames> extends Draggable<T> {
112
  constructor(containers: DraggableContainer, options: DroppableOptions);
113
  getClassNameFor(name: DroppableClassNames): string;
114
}
115

116
interface DroppableOptions extends DraggableOptions {
117
  dropzone: string | NodeList | HTMLElement[] | (() => NodeList | HTMLElement[]);
118
  classes?: {[key in DroppableClassNames]: string};
119
}
120
```
121

122
[Droppable Zones](./droppable.md)
123

124
### Swappable Elements
125

126
Enable element swapping where dragging over another element exchanges their positions. Order-independent interaction for grid layouts and card arrangements.
127

128
```typescript { .api }
129
class Swappable<T = SwappableEventNames> extends Draggable<T> {
130
  constructor(containers: DraggableContainer, options?: DraggableOptions);
131
}
132
```
133

134
[Swappable Elements](./swappable.md)
135

136
### Event System
137

138
Comprehensive event lifecycle with drag events, specialized events for each draggable type, and plugin-specific events. All events extend AbstractEvent with cancellation support.
139

140
```typescript { .api }
141
abstract class AbstractEvent<TData = {[key: string]: any}> {
142
  readonly type: string;
143
  readonly cancelable: boolean;
144
  constructor(data: TData);
145
  cancel(): void;
146
  canceled(): boolean;
147
  clone(data?: Partial<TData>): AbstractEvent<TData>;
148
}
149

150
export {AbstractEvent as BaseEvent};
151
```
152

153
[Events](./events.md)
154

155
### Sensors
156

157
Input detection system supporting mouse, touch, native drag events, and force touch. Pluggable architecture allows custom sensor implementation for specialized input handling.
158

159
```typescript { .api }
160
class Sensor {
161
  constructor(containers: HTMLElement | HTMLElement[] | NodeList, options?: SensorOptions);
162
  attach(): this;
163
  detach(): this;
164
  addContainer(...containers: HTMLElement[]): void;
165
  removeContainer(...containers: HTMLElement[]): void;
166
  trigger(element: HTMLElement, sensorEvent: SensorEvent): SensorEvent;
167
}
168
```
169

170
[Sensors](./sensors.md)
171

172
### Plugins
173

174
Extensible plugin system with built-in plugins for mirror elements, auto-scrolling, accessibility announcements, focus management, collision detection, and animations.
175

176
```typescript { .api }
177
abstract class AbstractPlugin {
178
  constructor(draggable: Draggable);
179
  protected abstract attach(): void;
180
  protected abstract detach(): void;
181
}
182

183
export {AbstractPlugin as BasePlugin};
184
```
185

186
[Plugins](./plugins.md)
187

188
## Types
189

190
```typescript { .api }
191
interface DraggableOptions {
192
  draggable?: string;
193
  distance?: number;
194
  handle?: string | NodeList | HTMLElement[] | HTMLElement | ((currentElement: HTMLElement) => HTMLElement);
195
  delay?: number | DelayOptions;
196
  placedTimeout?: number;
197
  plugins?: (typeof AbstractPlugin)[];
198
  sensors?: Sensor[];
199
  exclude?: {
200
    plugins?: (typeof AbstractPlugin)[];
201
    sensors?: (typeof Sensor)[];
202
  };
203
  classes?: {[key in DraggableClassNames]: string | string[]};
204
  announcements?: AnnouncementOptions;
205
  collidables?: Collidables;
206
  mirror?: MirrorOptions;
207
  scrollable?: ScrollableOptions;
208
  swapAnimation?: SwapAnimationOptions;
209
  sortAnimation?: SortAnimationOptions;
210
}
211

212
interface DelayOptions {
213
  mouse?: number;
214
  drag?: number;
215
  touch?: number;
216
}
217

218
type DraggableClassNames =
219
  | 'body:dragging'
220
  | 'container:dragging'
221
  | 'source:dragging'
222
  | 'source:placed'
223
  | 'container:placed'
224
  | 'draggable:over'
225
  | 'container:over'
226
  | 'source:original'
227
  | 'mirror';
228
```