0
# Interactions
1

2
jQuery UI interactions provide mouse-based behaviors for dragging, dropping, resizing, selecting, and sorting elements. These widgets inherit from the mouse widget and share common interaction patterns.
3

4
## Capabilities
5

6
### Draggable
7

8
Makes elements draggable with mouse interaction and extensive customization options.
9

10
```javascript { .api }
11
/**
12
 * Creates a draggable widget
13
 * @param {DraggableOptions} options - Configuration options
14
 */
15
$(...).draggable(options);
16

17
interface DraggableOptions {
18
  addClasses?: boolean;               // Add ui-draggable class (default: true)
19
  appendTo?: string | Element;        // Element to append helper to
20
  axis?: 'x' | 'y' | false;         // Constrain dragging to axis
21
  cancel?: string;                   // Selector for elements that cancel dragging
22
  classes?: object;                  // CSS classes to apply
23
  connectToSortable?: string;        // Selector for sortable containers
24
  containment?: string | Element | Array; // Containment boundary
25
  cursor?: string;                   // CSS cursor during drag
26
  cursorAt?: { top?: number, left?: number, right?: number, bottom?: number }; // Cursor position relative to helper
27
  delay?: number;                    // Delay in milliseconds before dragging starts
28
  disabled?: boolean;                // Disable the draggable
29
  distance?: number;                 // Distance in pixels before dragging starts
30
  grid?: [number, number];           // Snap to grid coordinates
31
  handle?: string | Element;         // Handle selector for dragging
32
  helper?: 'original' | 'clone' | Function; // Helper element type
33
  iframeFix?: boolean | string;      // Fix iframe mousemove issues
34
  opacity?: number;                  // Opacity of helper during drag
35
  refreshPositions?: boolean;        // Refresh droppable positions during drag
36
  revert?: boolean | 'valid' | 'invalid' | Function; // Revert behavior
37
  revertDuration?: number;           // Revert animation duration
38
  scope?: string;                    // Scope for droppable interaction
39
  scroll?: boolean;                  // Enable scrolling during drag
40
  scrollSensitivity?: number;        // Distance from edge to start scrolling
41
  scrollSpeed?: number;              // Scroll speed
42
  snap?: boolean | string;           // Snap to elements
43
  snapMode?: 'inner' | 'outer' | 'both'; // Snap mode
44
  snapTolerance?: number;            // Snap tolerance in pixels
45
  stack?: string;                    // Selector for elements to stack
46
  zIndex?: number;                   // Z-index of helper during drag
47
}
48
```
49

50
**Events:**
51
- `dragcreate` - Triggered when draggable is created
52
- `dragstart` - Triggered when dragging starts
53
- `drag` - Triggered during dragging
54
- `dragstop` - Triggered when dragging stops
55

56
**Usage Examples:**
57
```javascript
58
// Basic draggable
59
$('#draggable').draggable();
60

61
// Constrained to container
62
$('#draggable').draggable({
63
  containment: '#container'
64
});
65

66
// Snap to grid
67
$('#draggable').draggable({
68
  grid: [20, 20]
69
});
70

71
// Custom helper
72
$('#draggable').draggable({
73
  helper: 'clone',
74
  opacity: 0.7
75
});
76
```
77

78
### Droppable
79

80
Makes elements targets for draggable elements with customizable acceptance criteria.
81

82
```javascript { .api }
83
/**
84
 * Creates a droppable widget
85
 * @param {DroppableOptions} options - Configuration options
86
 */
87
$(...).droppable(options);
88

89
interface DroppableOptions {
90
  accept?: string | Function;         // Selector or function for acceptable draggables
91
  activeClass?: string;              // Class applied when acceptable draggable is being dragged
92
  addClasses?: boolean;              // Add ui-droppable class (default: true)
93
  classes?: object;                  // CSS classes to apply
94
  disabled?: boolean;                // Disable the droppable
95
  greedy?: boolean;                  // Prevent event propagation to parent droppables
96
  hoverClass?: string;               // Class applied when acceptable draggable hovers
97
  scope?: string;                    // Scope for draggable interaction
98
  tolerance?: 'fit' | 'intersect' | 'pointer' | 'touch'; // Drop tolerance
99
}
100
```
101

102
**Events:**
103
- `dropactivate` - Triggered when acceptable draggable starts dragging
104
- `dropcreate` - Triggered when droppable is created
105
- `dropdeactivate` - Triggered when acceptable draggable stops dragging
106
- `dropdrop` - Triggered when acceptable draggable is dropped
107
- `dropout` - Triggered when acceptable draggable moves out
108
- `dropover` - Triggered when acceptable draggable moves over
109

110
**Usage Examples:**
111
```javascript
112
// Basic droppable
113
$('#droppable').droppable({
114
  drop: function(event, ui) {
115
    $(this).addClass('dropped');
116
  }
117
});
118

119
// Accept specific elements
120
$('#droppable').droppable({
121
  accept: '.draggable-item',
122
  hoverClass: 'drop-hover',
123
  drop: function(event, ui) {
124
    ui.draggable.detach().appendTo(this);
125
  }
126
});
127

128
// Multiple droppables with scope
129
$('.droppable').droppable({
130
  scope: 'special',
131
  tolerance: 'intersect'
132
});
133
```
134

135
### Resizable
136

137
Makes elements resizable with drag handles and size constraints.
138

139
```javascript { .api }
140
/**
141
 * Creates a resizable widget
142
 * @param {ResizableOptions} options - Configuration options
143
 */
144
$(...).resizable(options);
145

146
interface ResizableOptions {
147
  alsoResize?: string | Element;      // Elements to resize simultaneously
148
  animate?: boolean;                 // Animate resize
149
  animateDuration?: number | string; // Animation duration
150
  animateEasing?: string;            // Animation easing
151
  aspectRatio?: boolean | number;    // Maintain aspect ratio
152
  autoHide?: boolean;                // Auto-hide handles when not hovering
153
  cancel?: string;                   // Selector for elements that cancel resizing
154
  classes?: object;                  // CSS classes to apply
155
  containment?: string | Element;    // Containment boundary
156
  delay?: number;                    // Delay before resizing starts
157
  disabled?: boolean;                // Disable the resizable
158
  distance?: number;                 // Distance before resizing starts
159
  ghost?: boolean;                   // Show ghost outline during resize
160
  grid?: [number, number];           // Snap to grid coordinates
161
  handles?: string | object;         // Resize handles configuration
162
  helper?: string;                   // Helper class name
163
  maxHeight?: number;                // Maximum height
164
  maxWidth?: number;                 // Maximum width
165
  minHeight?: number;                // Minimum height
166
  minWidth?: number;                 // Minimum width
167
}
168
```
169

170
**Events:**
171
- `resizecreate` - Triggered when resizable is created
172
- `resizestart` - Triggered when resizing starts
173
- `resize` - Triggered during resizing
174
- `resizestop` - Triggered when resizing stops
175

176
**Usage Examples:**
177
```javascript
178
// Basic resizable
179
$('#resizable').resizable();
180

181
// With constraints
182
$('#resizable').resizable({
183
  minWidth: 100,
184
  minHeight: 100,
185
  maxWidth: 500,
186
  maxHeight: 300
187
});
188

189
// Maintain aspect ratio
190
$('#resizable').resizable({
191
  aspectRatio: true,
192
  handles: 'n, e, s, w, ne, se, sw, nw'
193
});
194

195
// Ghost resize
196
$('#resizable').resizable({
197
  ghost: true,
198
  helper: 'resizable-helper'
199
});
200
```
201

202
### Selectable
203

204
Makes elements selectable with mouse interaction, supporting individual and lasso selection.
205

206
```javascript { .api }
207
/**
208
 * Creates a selectable widget
209
 * @param {SelectableOptions} options - Configuration options
210
 */
211
$(...).selectable(options);
212

213
interface SelectableOptions {
214
  appendTo?: string;                 // Element to append lasso helper to
215
  autoRefresh?: boolean;             // Auto-refresh element positions
216
  cancel?: string;                   // Selector for elements that cancel selection
217
  classes?: object;                  // CSS classes to apply
218
  delay?: number;                    // Delay before selection starts
219
  disabled?: boolean;                // Disable the selectable
220
  distance?: number;                 // Distance before selection starts
221
  filter?: string;                   // Selector for selectable elements
222
  tolerance?: 'fit' | 'touch';      // Selection tolerance
223
}
224
```
225

226
**Events:**
227
- `selectablecreate` - Triggered when selectable is created
228
- `selectablestart` - Triggered when selection starts
229
- `selectableselecting` - Triggered for each element being selected
230
- `selectableselected` - Triggered for each element after selection
231
- `selectableunselecting` - Triggered for each element being unselected
232
- `selectableunselected` - Triggered for each element after unselection  
233
- `selectablestop` - Triggered when selection stops
234

235
**Usage Examples:**
236
```javascript
237
// Basic selectable list
238
$('#selectable').selectable();
239

240
// Custom filter and tolerance
241
$('#selectable').selectable({
242
  filter: 'li',
243
  tolerance: 'touch'
244
});
245

246
// Handle selection events
247
$('#selectable').selectable({
248
  selected: function(event, ui) {
249
    $(ui.selected).addClass('highlighted');
250
  },
251
  unselected: function(event, ui) {
252
    $(ui.unselected).removeClass('highlighted');
253
  }
254
});
255
```
256

257
### Sortable
258

259
Makes list elements sortable by dragging with extensive customization options.
260

261
```javascript { .api }
262
/**
263
 * Creates a sortable widget
264
 * @param {SortableOptions} options - Configuration options
265
 */
266
$(...).sortable(options);
267

268
/**
269
 * Cancels current sort operation
270
 */
271
$(...).sortable('cancel');
272

273
/**
274
 * Refreshes cached information about sortable items
275
 */
276
$(...).sortable('refresh');
277

278
/**
279
 * Refreshes cached position information
280
 */
281
$(...).sortable('refreshPositions');
282

283
/**
284
 * Serializes sortable items to URL query string
285
 * @param {object} options - Serialization options
286
 * @returns {string} Query string
287
 */
288
$(...).sortable('serialize', options);
289

290
/**
291
 * Returns array of item IDs in current order
292
 * @param {object} options - Array options
293
 * @returns {string[]} Array of IDs
294
 */
295
$(...).sortable('toArray', options);
296

297
interface SortableOptions {
298
  appendTo?: string | Element;        // Element to append helper to
299
  axis?: 'x' | 'y' | false;         // Constrain sorting to axis
300
  cancel?: string;                   // Selector for elements that cancel sorting
301
  classes?: object;                  // CSS classes to apply
302
  connectWith?: string;              // Selector for connected sortables
303
  containment?: string | Element | Array; // Containment boundary
304
  cursor?: string;                   // CSS cursor during sort
305
  cursorAt?: { top?: number, left?: number, right?: number, bottom?: number }; // Cursor position
306
  delay?: number;                    // Delay before sorting starts
307
  disabled?: boolean;                // Disable the sortable
308
  distance?: number;                 // Distance before sorting starts
309
  dropOnEmpty?: boolean;             // Allow dropping on empty lists
310
  forceHelperSize?: boolean;         // Force helper to have size
311
  forcePlaceholderSize?: boolean;    // Force placeholder to have size
312
  grid?: [number, number];           // Snap to grid coordinates
313
  handle?: string | Element;         // Handle selector for sorting
314
  helper?: 'original' | 'clone' | Function; // Helper element type
315
  items?: string;                    // Selector for sortable items
316
  opacity?: number;                  // Opacity of helper during sort
317
  placeholder?: string;              // Class name for placeholder
318
  revert?: boolean | number;         // Revert animation
319
  scroll?: boolean;                  // Enable scrolling during sort
320
  scrollSensitivity?: number;        // Distance from edge to start scrolling
321
  scrollSpeed?: number;              // Scroll speed
322
  tolerance?: 'intersect' | 'pointer'; // Sort tolerance
323
  zIndex?: number;                   // Z-index of helper during sort
324
}
325
```
326

327
**Events:**
328
- `sortactivate` - Triggered when sorting starts on connected sortable
329
- `sortbeforeStop` - Triggered before sorting stops
330
- `sortchange` - Triggered when sort order changes
331
- `sortcreate` - Triggered when sortable is created
332
- `sortdeactivate` - Triggered when sorting stops on connected sortable
333
- `sortout` - Triggered when item moves out of connected sortable
334
- `sortover` - Triggered when item moves over connected sortable
335
- `sortreceive` - Triggered when item is received from connected sortable
336
- `sortremove` - Triggered when item is removed to connected sortable
337
- `sortsort` - Triggered during sorting
338
- `sortstart` - Triggered when sorting starts
339
- `sortstop` - Triggered when sorting stops
340
- `sortupdate` - Triggered when sort order changes and DOM position updates
341

342
**Usage Examples:**
343
```javascript
344
// Basic sortable list
345
$('#sortable').sortable();
346

347
// Connected sortables
348
$('#list1, #list2').sortable({
349
  connectWith: '.connected-sortable'
350
});
351

352
// Handle sort events
353
$('#sortable').sortable({
354
  update: function(event, ui) {
355
    var order = $(this).sortable('toArray');
356
    console.log('New order:', order);
357
  }
358
});
359

360
// Serialize to form data
361
$('#sortable').sortable({
362
  stop: function() {
363
    var serialized = $(this).sortable('serialize');
364
    $.post('update-order.php', serialized);
365
  }
366
});
367

368
// Custom placeholder and helper
369
$('#sortable').sortable({
370
  placeholder: 'sort-highlight',
371
  helper: 'clone',
372
  opacity: 0.6
373
});
374
```
375

376
## Mouse Widget Base
377

378
All interaction widgets inherit from the mouse widget, which provides common mouse handling:
379

380
```javascript { .api }
381
interface MouseOptions {
382
  cancel?: string;                   // Selector for elements that cancel mouse interaction
383
  delay?: number;                    // Delay in milliseconds before interaction starts
384
  distance?: number;                 // Distance in pixels before interaction starts
385
}
386
```
387

388
**Mouse Events:**
389
- Mouse widgets trigger standard jQuery UI widget events
390
- All mouse interactions respect the `cancel`, `delay`, and `distance` options
391
- Custom mouse handling can be implemented by extending `$.ui.mouse`
392

393
## Types
394

395
```javascript { .api }
396
// Common interaction event object
397
interface InteractionEvent {
398
  type: string;
399
  target: Element;
400
  currentTarget: Element;
401
  originalEvent: MouseEvent;
402
  helper?: jQuery;
403
  position?: { top: number, left: number };
404
  offset?: { top: number, left: number };
405
}
406

407
// Draggable-specific event object
408
interface DraggableEvent extends InteractionEvent {
409
  helper: jQuery;
410
  position: { top: number, left: number };
411
  offset: { top: number, left: number };
412
}
413

414
// Droppable-specific event object  
415
interface DroppableEvent extends InteractionEvent {
416
  draggable: jQuery;
417
}
418

419
// Resizable-specific event object
420
interface ResizableEvent extends InteractionEvent {
421
  size: { width: number, height: number };
422
  originalSize: { width: number, height: number };
423
  position: { top: number, left: number };
424
  originalPosition: { top: number, left: number };
425
}
426

427
// Selectable-specific event object
428
interface SelectableEvent extends InteractionEvent {
429
  selecting?: Element;
430
  selected?: Element;
431
  unselecting?: Element;
432
  unselected?: Element;
433
}
434

435
// Sortable-specific event object
436
interface SortableEvent extends InteractionEvent {
437
  item: jQuery;
438
  helper: jQuery;
439
  position: { top: number, left: number };
440
  offset: { top: number, left: number };
441
  sender?: jQuery;
442
  placeholder: jQuery;
443
}
444

445
// Utility types for coordinates and dimensions
446
interface Coordinates {
447
  top: number;
448
  left: number;
449
}
450

451
interface Dimensions {
452
  width: number;
453
  height: number;
454
}
455

456
interface Rectangle extends Coordinates, Dimensions {}
457
```