npm-react-aria

1
# Drag and Drop
2

3
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.
4

5
## Capabilities
6

7
### Individual Drag and Drop
8

9
Basic drag and drop functionality for individual elements.
10

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

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

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

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

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

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

67
### Collection Drag and Drop
68

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

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

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

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

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

113
### Item-Level Drag and Drop
114

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

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

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

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

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

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

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

165
### Clipboard Integration
166

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

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

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

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

200
### Drag Preview Component
201

202
Component for customizing drag preview appearance.
203

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

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

220
## Types
221

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

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

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

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

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

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

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

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

278
**Usage Example:**
279

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

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

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

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

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