0
# Drag and Drop
1

2
Comprehensive drag and drop system for building interactive interfaces with accessible keyboard navigation, screen reader support, and cross-platform compatibility. Supports both individual draggable items and full collection-based drag and drop operations.
3

4
## Capabilities
5

6
### Individual Drag and Drop
7

8
Basic drag and drop functionality for individual elements.
9

10
```typescript { .api }
11
/**
12
 * Provides drag behavior for an element
13
 * @param options - Drag configuration options
14
 * @returns Drag result with props and state
15
 */
16
function useDrag(options: DragOptions): DragResult;
17

18
/**
19
 * Provides drop behavior for an element
20
 * @param options - Drop configuration options
21
 * @returns Drop result with props and state
22
 */
23
function useDrop(options: DropOptions): DropResult;
24

25
interface DragOptions {
26
  /** Handler called when drag starts */
27
  onDragStart?: (e: DragStartEvent) => void;
28
  /** Handler called when drag ends */
29
  onDragEnd?: (e: DragEndEvent) => void;
30
  /** Data to transfer during drag operation */
31
  getItems: () => DragItem[];
32
  /** Preview element or render function */
33
  preview?: DragPreview;
34
  /** Whether drag is allowed */
35
  isDisabled?: boolean;
36
}
37

38
interface DropOptions {
39
  /** Handler called when items are dropped */
40
  onDrop?: (e: DropEvent) => void;
41
  /** Handler called when drag enters the drop zone */
42
  onDragEnter?: (e: DragEnterEvent) => void;
43
  /** Handler called when drag leaves the drop zone */
44
  onDragLeave?: (e: DragLeaveEvent) => void;
45
  /** Function to determine if drop is allowed */
46
  shouldAcceptDrop?: (types: Set<string>) => boolean;
47
  /** Whether drop is allowed */
48
  isDisabled?: boolean;
49
}
50

51
interface DragResult {
52
  /** Props to spread on the draggable element */
53
  dragProps: DOMAttributes<Element>;
54
  /** Whether the element is currently being dragged */
55
  isDragging: boolean;
56
}
57

58
interface DropResult {
59
  /** Props to spread on the drop target element */
60
  dropProps: DOMAttributes<Element>;
61
  /** Whether a drag is currently over the drop zone */
62
  isDropTarget: boolean;
63
}
64
```
65

66
### Collection Drag and Drop
67

68
Advanced drag and drop for collections like lists and grids with reordering and multi-selection support.
69

70
```typescript { .api }
71
/**
72
 * Provides drag and drop behavior for collections
73
 * @param props - Draggable collection configuration
74
 * @returns Collection drag utilities
75
 */
76
function useDraggableCollection(props: DraggableCollectionProps): DraggableCollectionResult;
77

78
/**
79
 * Provides drop behavior for collections
80
 * @param props - Droppable collection configuration
81
 * @returns Collection drop utilities
82
 */
83
function useDroppableCollection(props: DroppableCollectionProps): DroppableCollectionResult;
84

85
interface DraggableCollectionProps {
86
  /** Selection manager for the collection */
87
  selectionManager: SelectionManager;
88
  /** Handler called when drag starts */
89
  onDragStart?: (e: DragStartEvent) => void;
90
  /** Handler called when drag ends */
91
  onDragEnd?: (e: DragEndEvent) => void;
92
  /** Function to get drag data for items */
93
  getItems: (keys: Set<Key>) => DragItem[];
94
  /** Preview configuration */
95
  preview?: DragPreview;
96
}
97

98
interface DroppableCollectionProps {
99
  /** Collection state */
100
  collection: Collection<any>;
101
  /** Selection manager */
102
  selectionManager: SelectionManager;
103
  /** Handler for drop operations */
104
  onDrop?: (e: DropEvent) => void;
105
  /** Handler for reorder operations */
106
  onReorder?: (e: ReorderEvent) => void;
107
  /** Function to determine accepted drop types */
108
  shouldAcceptDrop?: (target: DropTarget, types: Set<string>) => boolean;
109
}
110
```
111

112
### Item-Level Drag and Drop
113

114
Hooks for individual items within draggable/droppable collections.
115

116
```typescript { .api }
117
/**
118
 * Provides drag behavior for individual collection items
119
 * @param props - Draggable item configuration
120
 * @returns Item drag utilities
121
 */
122
function useDraggableItem(props: DraggableItemProps): DraggableItemResult;
123

124
/**
125
 * Provides drop behavior for individual collection items
126
 * @param props - Droppable item configuration
127
 * @returns Item drop utilities
128
 */
129
function useDroppableItem(props: DroppableItemProps): DroppableItemResult;
130

131
/**
132
 * Provides drop indicator for showing drop positions
133
 * @param props - Drop indicator configuration
134
 * @returns Drop indicator utilities
135
 */
136
function useDropIndicator(props: DropIndicatorProps): DropIndicatorResult;
137

138
interface DraggableItemProps {
139
  /** Item key */
140
  key: Key;
141
  /** Whether dragging is disabled for this item */
142
  isDisabled?: boolean;
143
  /** Whether the item has a drag handle */
144
  hasDragHandle?: boolean;
145
}
146

147
interface DroppableItemProps {  
148
  /** Item key */
149
  key: Key;
150
  /** Drop target configuration */
151
  target: DropTarget;
152
  /** Whether dropping is disabled for this item */
153
  isDisabled?: boolean;
154
}
155

156
interface DropIndicatorProps {
157
  /** Drop target for the indicator */
158
  target: DropTarget;
159
  /** Whether the indicator is disabled */
160
  isDisabled?: boolean;
161
}
162
```
163

164
### Clipboard Integration
165

166
Utilities for clipboard operations integrated with drag and drop.
167

168
```typescript { .api }
169
/**
170
 * Provides clipboard functionality with drag and drop integration
171
 * @param options - Clipboard configuration
172
 * @returns Clipboard utilities
173
 */
174
function useClipboard(options: ClipboardOptions): ClipboardResult;
175

176
interface ClipboardOptions {
177
  /** Handler called when items are copied */
178
  onCopy?: (items: ClipboardItem[]) => void;
179
  /** Handler called when items are cut */
180
  onCut?: (items: ClipboardItem[]) => void;
181
  /** Handler called when items are pasted */
182
  onPaste?: (items: ClipboardItem[]) => void;
183
  /** Function to get clipboard data */
184
  getItems?: () => ClipboardItem[];
185
}
186

187
interface ClipboardResult {
188
  /** Copy selected items to clipboard */
189
  copy: () => void;
190
  /** Cut selected items to clipboard */
191
  cut: () => void;
192
  /** Paste items from clipboard */
193
  paste: () => void;
194
  /** Whether clipboard operations are available */
195
  isSupported: boolean;
196
}
197
```
198

199
### Drag Preview Component
200

201
Component for customizing drag preview appearance.
202

203
```typescript { .api }
204
/**
205
 * Component for rendering custom drag previews
206
 */
207
function DragPreview(props: DragPreviewProps): JSX.Element;
208

209
interface DragPreviewProps {
210
  /** Preview content to render */
211
  children: ReactNode;
212
  /** Offset from cursor position */
213
  offset?: { x: number; y: number };
214
  /** Whether to use default browser preview */
215
  useDefaultPreview?: boolean;
216
}
217
```
218

219
## Types
220

221
```typescript { .api }
222
interface DragItem {
223
  /** Drag data type */
224
  type: string;
225
  /** Item data */
226
  data: any;
227
  /** Text representation */
228
  textValue?: string;
229
}
230

231
interface DragStartEvent {
232
  /** Items being dragged */
233
  items: DragItem[];
234
  /** Pointer type */
235
  pointerType: 'mouse' | 'touch' | 'pen' | 'keyboard';
236
}
237

238
interface DragEndEvent {
239
  /** Whether the drop was successful */
240
  isSuccessful: boolean;
241
  /** Operation performed */
242
  operation: 'move' | 'copy' | 'link' | 'cancel';
243
}
244

245
interface DropEvent {
246
  /** Items being dropped */
247
  items: DropItem[];
248
  /** Drop target */
249
  target: DropTarget;
250
  /** Drop operation */
251
  operation: 'move' | 'copy' | 'link';
252
}
253

254
interface DropTarget {
255
  /** Target type */
256
  type: 'item' | 'collection' | 'root';
257
  /** Target key (for item targets) */
258
  key?: Key;
259
  /** Drop position relative to target */
260
  dropPosition?: 'before' | 'after' | 'on';
261
}
262

263
interface ReorderEvent {
264
  /** Keys of items being reordered */
265
  keys: Set<Key>;
266
  /** Target drop position */
267
  target: DropTarget;
268
}
269

270
type DIRECTORY_DRAG_TYPE = 'application/vnd.react-aria.directory';
271

272
function isDirectoryDropItem(item: DropItem): boolean;
273
function isFileDropItem(item: DropItem): boolean;
274
function isTextDropItem(item: DropItem): boolean;
275
```
276

277
**Usage Example:**
278

279
```typescript
280
import { useDrag, useDrop } from "react-aria";
281

282
function DraggableItem({ item }) {
283
  let { dragProps, isDragging } = useDrag({
284
    getItems: () => [{ type: 'text/plain', data: item.text }],
285
    onDragEnd: (e) => console.log('Drag ended:', e.isSuccessful)
286
  });
287

288
  return (
289
    <div
290
      {...dragProps}
291
      className={`draggable-item ${isDragging ? 'dragging' : ''}`}
292
    >
293
      {item.text}
294
    </div>
295
  );
296
}
297

298
function DropZone({ onDrop }) {
299
  let { dropProps, isDropTarget } = useDrop({
300
    onDrop: (e) => onDrop(e.items),
301
    shouldAcceptDrop: (types) => types.has('text/plain')
302
  });
303

304
  return (
305
    <div
306
      {...dropProps}
307
      className={`drop-zone ${isDropTarget ? 'drop-target' : ''}`}
308
    >
309
      Drop items here
310
    </div>
311
  );
312
}
313
```