npm-react-aria

1
# Interactions
2

3
Low-level interaction hooks for handling user input across different devices and interaction models. These hooks provide normalized event handling for mouse, touch, keyboard, and screen reader interactions.
4

5
## Capabilities
6

7
### Press
8

9
Provides press interaction handling across mouse, touch, and keyboard.
10

11
```typescript { .api }
12
/**
13
 * Provides press interaction handling
14
 * @param props - Press configuration
15
 * @returns Press result with event handlers
16
 */
17
function usePress(props: PressHookProps): PressResult;
18

19
interface PressHookProps extends PressProps {
20
  /** Ref to the target element */
21
  ref?: RefObject<Element>;
22
}
23

24
interface PressProps {
25
  /** Handler called when press starts */
26
  onPressStart?: (e: PressEvent) => void;
27
  /** Handler called when press ends */
28
  onPressEnd?: (e: PressEvent) => void;
29
  /** Handler called when press changes */
30
  onPressChange?: (isPressed: boolean) => void;
31
  /** Handler called when press is released over target */
32
  onPressUp?: (e: PressEvent) => void;
33
  /** Handler called when press is completed */
34
  onPress?: (e: PressEvent) => void;
35
  /** Whether press events are disabled */
36
  isDisabled?: boolean;
37
  /** Whether to prevent focus on press (mobile) */
38
  preventFocusOnPress?: boolean;
39
  /** Whether press should cancel when pointer exits */
40
  shouldCancelOnPointerExit?: boolean;
41
  /** Whether text selection should be allowed during press */
42
  allowTextSelectionOnPress?: boolean;
43
}
44

45
interface PressResult {
46
  /** Whether the element is currently pressed */
47
  isPressed: boolean;
48
  /** Props to spread on the target element */
49
  pressProps: DOMAttributes<Element>;
50
}
51

52
interface PressEvent {
53
  /** Type of press event */
54
  type: 'pressstart' | 'pressend' | 'pressup' | 'press';
55
  /** Input type that triggered the event */
56
  pointerType: 'mouse' | 'pen' | 'touch' | 'keyboard' | 'virtual';
57
  /** Target element */
58
  target: Element;
59
  /** Whether shift key was pressed */
60
  shiftKey: boolean;
61
  /** Whether ctrl key was pressed */
62
  ctrlKey: boolean;
63
  /** Whether meta key was pressed */
64
  metaKey: boolean;
65
  /** Whether alt key was pressed */
66
  altKey: boolean;
67
  /** X coordinate relative to target */
68
  x: number;
69
  /** Y coordinate relative to target */
70
  y: number;
71
  /** Continue propagation */
72
  continuePropagation(): void;
73
}
74
```
75

76
### Long Press
77

78
Provides long press interaction handling with customizable delay.
79

80
```typescript { .api }
81
/**
82
 * Provides long press interaction handling
83
 * @param props - Long press configuration
84
 * @returns Long press result with event handlers
85
 */
86
function useLongPress(props: LongPressProps): LongPressResult;
87

88
interface LongPressProps {
89
  /** Whether long press is disabled */
90
  isDisabled?: boolean;
91
  /** Handler called when long press is triggered */
92
  onLongPressStart?: (e: LongPressEvent) => void;
93
  /** Handler called when long press ends */
94
  onLongPressEnd?: (e: LongPressEvent) => void;
95
  /** Handler called when long press completes */
96
  onLongPress?: (e: LongPressEvent) => void;
97
  /** Long press threshold in milliseconds */
98
  threshold?: number;
99
  /** Accessibility description for long press action */
100
  accessibilityDescription?: string;
101
}
102

103
interface LongPressResult {
104
  /** Props to spread on the target element */
105
  longPressProps: DOMAttributes<Element>;
106
}
107

108
interface LongPressEvent {
109
  /** Type of long press event */
110
  type: 'longpressstart' | 'longpressend' | 'longpress';
111
  /** Input type that triggered the event */
112
  pointerType: 'mouse' | 'pen' | 'touch' | 'keyboard' | 'virtual';
113
  /** Target element */
114
  target: Element;
115
  /** Whether shift key was pressed */
116
  shiftKey: boolean;
117
  /** Whether ctrl key was pressed */
118
  ctrlKey: boolean;
119
  /** Whether meta key was pressed */
120
  metaKey: boolean;
121
  /** Whether alt key was pressed */
122
  altKey: boolean;
123
}
124
```
125

126
### Hover
127

128
Provides hover interaction handling with proper touch device support.
129

130
```typescript { .api }
131
/**
132
 * Provides hover interaction handling
133
 * @param props - Hover configuration
134
 * @returns Hover result with event handlers
135
 */
136
function useHover(props: HoverProps): HoverResult;
137

138
interface HoverProps {
139
  /** Handler called when hover starts */
140
  onHoverStart?: (e: HoverEvent) => void;
141
  /** Handler called when hover ends */
142
  onHoverEnd?: (e: HoverEvent) => void;
143
  /** Handler called when hover changes */
144
  onHoverChange?: (isHovering: boolean) => void;
145
  /** Whether hover is disabled */
146
  isDisabled?: boolean;
147
}
148

149
interface HoverResult {
150
  /** Props to spread on the target element */
151
  hoverProps: DOMAttributes<Element>;
152
  /** Whether the element is currently hovered */
153
  isHovered: boolean;
154
}
155

156
interface HoverEvent {
157
  /** Type of hover event */
158
  type: 'hoverstart' | 'hoverend';
159
  /** Input type that triggered the event */
160
  pointerType: 'mouse' | 'pen';
161
  /** Target element */
162
  target: Element;
163
}
164
```
165

166
### Focus
167

168
Provides focus event handling with proper event normalization.
169

170
```typescript { .api }
171
/**
172
 * Provides focus event handling
173
 * @param props - Focus configuration
174
 * @returns Focus result with event handlers
175
 */
176
function useFocus(props: FocusProps): FocusResult;
177

178
interface FocusProps {
179
  /** Whether focus events are disabled */
180
  isDisabled?: boolean;
181
  /** Handler called when element receives focus */
182
  onFocus?: (e: FocusEvent) => void;
183
  /** Handler called when element loses focus */
184
  onBlur?: (e: FocusEvent) => void;
185
  /** Handler called when focus changes */
186
  onFocusChange?: (isFocused: boolean) => void;
187
}
188

189
interface FocusResult {
190
  /** Props to spread on the target element */
191
  focusProps: DOMAttributes<Element>;
192
}
193
```
194

195
### Focus Visible
196

197
Provides focus-visible state management for keyboard navigation styling.
198

199
```typescript { .api }
200
/**
201
 * Provides focus-visible state management
202
 * @param props - Focus visible configuration
203
 * @returns Focus visible result with state
204
 */
205
function useFocusVisible(props?: FocusVisibleProps): FocusVisibleResult;
206

207
interface FocusVisibleProps {
208
  /** Whether focus visible is disabled */
209
  isDisabled?: boolean;
210
  /** Auto-focus behavior */
211
  autoFocus?: boolean;
212
}
213

214
interface FocusVisibleResult {
215
  /** Whether focus is visible */
216
  isFocusVisible: boolean;
217
}
218
```
219

220
### Focus Within
221

222
Provides focus-within state tracking for container elements.
223

224
```typescript { .api }
225
/**
226
 * Provides focus-within state tracking
227
 * @param props - Focus within configuration
228
 * @returns Focus within result with event handlers
229
 */
230
function useFocusWithin(props: FocusWithinProps): FocusWithinResult;
231

232
interface FocusWithinProps {
233
  /** Whether focus within is disabled */
234
  isDisabled?: boolean;
235
  /** Handler called when focus enters the container */
236
  onFocusWithin?: (e: FocusEvent) => void;
237
  /** Handler called when focus leaves the container */
238
  onBlurWithin?: (e: FocusEvent) => void;
239
  /** Handler called when focus within changes */
240
  onFocusWithinChange?: (isFocusWithin: boolean) => void;
241
}
242

243
interface FocusWithinResult {
244
  /** Props to spread on the container element */
245
  focusWithinProps: DOMAttributes<Element>;
246
  /** Whether focus is within the container */
247
  isFocusWithin: boolean;
248
}
249
```
250

251
### Keyboard
252

253
Provides keyboard event handling with normalized key handling.
254

255
```typescript { .api }
256
/**
257
 * Provides keyboard event handling
258
 * @param props - Keyboard configuration
259
 * @returns Keyboard result with event handlers
260
 */
261
function useKeyboard(props: KeyboardProps): KeyboardResult;
262

263
interface KeyboardProps {
264
  /** Whether keyboard events are disabled */
265
  isDisabled?: boolean;
266
  /** Handler called on key down */
267
  onKeyDown?: (e: KeyboardEvent) => void;
268
  /** Handler called on key up */
269
  onKeyUp?: (e: KeyboardEvent) => void;
270
}
271

272
interface KeyboardResult {
273
  /** Props to spread on the target element */
274
  keyboardProps: DOMAttributes<Element>;
275
}
276
```
277

278
### Move
279

280
Provides move/drag interaction handling for pointer events.
281

282
```typescript { .api }
283
/**
284
 * Provides move/drag interaction handling
285
 * @param props - Move configuration
286
 * @returns Move result with event handlers
287
 */
288
function useMove(props: MoveEvents): MoveResult;
289

290
interface MoveEvents {
291
  /** Handler called when move starts */
292
  onMoveStart?: (e: MoveStartEvent) => void;
293
  /** Handler called during move */
294
  onMove?: (e: MoveMoveEvent) => void;
295
  /** Handler called when move ends */
296
  onMoveEnd?: (e: MoveEndEvent) => void;
297
}
298

299
interface MoveResult {
300
  /** Props to spread on the target element */
301
  moveProps: DOMAttributes<Element>;
302
}
303

304
interface MoveStartEvent {
305
  /** Type of move event */
306
  type: 'movestart';
307
  /** Input type */
308
  pointerType: 'mouse' | 'pen' | 'touch' | 'keyboard' | 'virtual';
309
  /** Whether shift key was pressed */
310
  shiftKey: boolean;
311
  /** Whether ctrl key was pressed */
312
  ctrlKey: boolean;
313
  /** Whether meta key was pressed */
314
  metaKey: boolean;
315
  /** Whether alt key was pressed */
316
  altKey: boolean;
317
}
318

319
interface MoveMoveEvent {
320
  /** Type of move event */
321
  type: 'move';
322
  /** Input type */
323
  pointerType: 'mouse' | 'pen' | 'touch' | 'keyboard' | 'virtual';
324
  /** Delta X movement */
325
  deltaX: number;
326
  /** Delta Y movement */
327
  deltaY: number;
328
  /** Whether shift key was pressed */
329
  shiftKey: boolean;
330
  /** Whether ctrl key was pressed */
331
  ctrlKey: boolean;
332
  /** Whether meta key was pressed */
333
  metaKey: boolean;
334
  /** Whether alt key was pressed */
335
  altKey: boolean;
336
}
337

338
interface MoveEndEvent {
339
  /** Type of move event */
340
  type: 'moveend';
341
  /** Input type */
342
  pointerType: 'mouse' | 'pen' | 'touch' | 'keyboard' | 'virtual';
343
  /** Whether shift key was pressed */
344
  shiftKey: boolean;
345
  /** Whether ctrl key was pressed */
346
  ctrlKey: boolean;
347
  /** Whether meta key was pressed */
348
  metaKey: boolean;
349
  /** Whether alt key was pressed */
350
  altKey: boolean;
351
}
352
```
353

354
### Interact Outside
355

356
Provides outside interaction detection for dismissing overlays.
357

358
```typescript { .api }
359
/**
360
 * Provides outside interaction detection
361
 * @param props - Interact outside configuration
362
 * @returns Event handlers for outside detection
363
 */
364
function useInteractOutside(props: InteractOutsideProps): void;
365

366
interface InteractOutsideProps {
367
  /** Ref to the element to monitor */
368
  ref: RefObject<Element>;
369
  /** Handler called when interaction occurs outside */
370
  onInteractOutside?: (e: InteractOutsideEvent) => void;
371
  /** Whether interact outside is disabled */
372
  isDisabled?: boolean;
373
  /** Handler to determine if interaction should be ignored */
374
  onInteractOutsideStart?: (e: InteractOutsideEvent) => void;
375
}
376

377
interface InteractOutsideEvent {
378
  /** Type of interaction */
379
  type: 'pointerdown' | 'pointerup' | 'focusin' | 'focusout';
380
  /** Target element */
381
  target: Element;
382
}
383
```
384

385
### Focusable
386

387
Provides focusable element behavior with keyboard and screen reader support.
388

389
```typescript { .api }
390
/**
391
 * Provides focusable element behavior
392
 * @param props - Focusable configuration
393
 * @param ref - Ref to the focusable element
394
 * @returns Focusable result with props and state
395
 */
396
function useFocusable(props: FocusableOptions, ref: RefObject<Element>): FocusableAria;
397

398
interface FocusableOptions {
399
  /** Whether the element should exclude from tab order */
400
  excludeFromTabOrder?: boolean;
401
  /** Whether the element is disabled */
402
  isDisabled?: boolean;
403
  /** Auto-focus behavior */
404
  autoFocus?: boolean;
405
}
406

407
interface FocusableAria {
408
  /** Props to spread on the focusable element */
409
  focusableProps: DOMAttributes<Element>;
410
}
411
```
412

413
### Drag and Drop
414

415
Provides comprehensive drag and drop interaction handling.
416

417
```typescript { .api }
418
/**
419
 * Provides drag behavior for elements
420
 * @param options - Drag configuration
421
 * @returns Drag result with props and state
422
 */
423
function useDrag(options: DragOptions): DragResult;
424

425
/**
426
 * Provides drop behavior for elements
427
 * @param options - Drop configuration
428
 * @returns Drop result with props and state
429
 */
430
function useDrop(options: DropOptions): DropResult;
431

432
/**
433
 * Provides draggable collection behavior
434
 * @param options - Draggable collection configuration
435
 * @returns Collection drag result
436
 */
437
function useDraggableCollection(options: DraggableCollectionOptions): DroppableCollectionResult;
438

439
/**
440
 * Provides droppable collection behavior
441
 * @param options - Droppable collection configuration
442
 * @returns Collection drop result
443
 */
444
function useDroppableCollection(options: DroppableCollectionOptions): DroppableCollectionResult;
445

446
/**
447
 * Provides individual draggable item behavior
448
 * @param props - Draggable item configuration
449
 * @returns Draggable item result
450
 */
451
function useDraggableItem(props: DraggableItemProps, ref: RefObject<Element>): DraggableItemResult;
452

453
/**
454
 * Provides individual droppable item behavior
455
 * @param options - Droppable item configuration
456
 * @param ref - Ref to the droppable element
457
 * @returns Droppable item result
458
 */
459
function useDroppableItem(options: DroppableItemOptions, ref: RefObject<Element>): DroppableItemResult;
460

461
/**
462
 * Provides drop indicator behavior
463
 * @param props - Drop indicator configuration
464
 * @param ref - Ref to the indicator element
465
 * @returns Drop indicator result
466
 */
467
function useDropIndicator(props: DropIndicatorProps, ref: RefObject<Element>): DropIndicatorAria;
468

469
/**
470
 * Component for rendering drag previews
471
 * @param props - Drag preview configuration
472
 * @returns Drag preview component
473
 */
474
function DragPreview(props: DragPreviewProps): JSX.Element;
475

476
/**
477
 * Drop target delegate for list components
478
 */
479
class ListDropTargetDelegate implements DropTargetDelegate {
480
  /** Get drop target for a point */
481
  getDropTarget(target: DropTarget, types: Set<string>): DropTarget | null;
482
  /** Check if drop is allowed */
483
  isValidDropTarget(target: DropTarget, types: Set<string>): boolean;
484
}
485

486
/**
487
 * Constant for directory drag type
488
 */
489
const DIRECTORY_DRAG_TYPE: string;
490

491
/**
492
 * Type guard to check if drop item is a directory
493
 * @param item - Drop item to check
494
 * @returns Whether item is a directory
495
 */
496
function isDirectoryDropItem(item: DropItem): item is DirectoryDropItem;
497

498
/**
499
 * Type guard to check if drop item is a file
500
 * @param item - Drop item to check
501
 * @returns Whether item is a file
502
 */
503
function isFileDropItem(item: DropItem): item is FileDropItem;
504

505
/**
506
 * Type guard to check if drop item is text
507
 * @param item - Drop item to check
508
 * @returns Whether item is text
509
 */
510
function isTextDropItem(item: DropItem): item is TextDropItem;
511

512
interface DragOptions {
513
  /** Handler called when drag starts */
514
  onDragStart?: (e: DragStartEvent) => void;
515
  /** Handler called during drag */
516
  onDragMove?: (e: DragMoveEvent) => void;
517
  /** Handler called when drag ends */
518
  onDragEnd?: (e: DragEndEvent) => void;
519
  /** Get drag data for the operation */
520
  getItems: () => DragItem[];
521
  /** Preview component */
522
  preview?: DragPreviewRenderer;
523
  /** Whether drag is disabled */
524
  isDisabled?: boolean;
525
}
526

527
interface DragResult {
528
  /** Props for the draggable element */
529
  dragProps: DOMAttributes<Element>;
530
  /** Whether element is currently being dragged */
531
  isDragging: boolean;
532
}
533

534
interface DropOptions {
535
  /** Ref to the drop target element */
536
  ref: RefObject<Element>;
537
  /** Handler called when drop occurs */
538
  onDrop?: (e: DropEvent) => void;
539
  /** Handler called when drag enters */
540
  onDropEnter?: (e: DropEnterEvent) => void;
541
  /** Handler called when drag exits */
542
  onDropExit?: (e: DropExitEvent) => void;
543
  /** Handler called during drag over */
544
  onDropMove?: (e: DropMoveEvent) => void;
545
  /** Get drop operation for items */
546
  getDropOperation?: (target: DropTarget, types: Set<string>, allowedOperations: DropOperation[]) => DropOperation;
547
  /** Accept drop delegate */
548
  acceptedDragTypes?: string[];
549
  /** Whether drop is disabled */
550
  isDisabled?: boolean;
551
}
552

553
interface DropResult {
554
  /** Props for the droppable element */
555
  dropProps: DOMAttributes<Element>;
556
  /** Whether drag is currently over */
557
  isDropTarget: boolean;
558
}
559
```
560

561
### Clipboard
562

563
Provides clipboard operations with proper permissions and fallbacks.
564

565
```typescript { .api }
566
/**
567
 * Provides clipboard operations
568
 * @param props - Clipboard configuration
569
 * @returns Clipboard result with operations
570
 */
571
function useClipboard(props?: ClipboardProps): ClipboardResult;
572

573
interface ClipboardProps {
574
  /** Handler called when copy succeeds */
575
  onCopy?: () => void;
576
  /** Handler called when copy fails */
577
  onError?: () => void;
578
}
579

580
interface ClipboardResult {
581
  /** Copy text to clipboard */
582
  copy(text: string): Promise<void>;
583
  /** Copy data items to clipboard */
584
  copyItems(items: ClipboardItem[]): Promise<void>;
585
  /** Paste from clipboard */
586
  paste(): Promise<string>;
587
  /** Whether clipboard operations are supported */
588
  isSupported: boolean;
589
}
590
```
591

592
### Interaction Components
593

594
```typescript { .api }
595
/**
596
 * Component for pressable elements with interaction states
597
 */
598
function Pressable(props: PressableProps): JSX.Element;
599

600
/**
601
 * Component for focusable elements with proper semantics
602
 */
603
function Focusable(props: FocusableProps): JSX.Element;
604

605
interface PressableProps extends PressProps {
606
  /** Children render prop */
607
  children: (states: { isPressed: boolean }) => ReactNode;
608
  /** Element type to render */
609
  elementType?: React.ElementType;
610
}
611

612
interface FocusableProps extends FocusableOptions {
613
  /** Children content */
614
  children: ReactNode;
615
  /** Element type to render */
616
  elementType?: React.ElementType;
617
}
618
```
619

620
## Types
621

622
```typescript { .api }
623
type PointerType = 'mouse' | 'pen' | 'touch' | 'keyboard' | 'virtual';
624

625
interface KeyboardEvent {
626
  /** Type of keyboard event */
627
  type: 'keydown' | 'keyup';
628
  /** Key that was pressed */
629
  key: string;
630
  /** Key code */
631
  code: string;
632
  /** Whether shift key was pressed */
633
  shiftKey: boolean;
634
  /** Whether ctrl key was pressed */
635
  ctrlKey: boolean;
636
  /** Whether meta key was pressed */
637
  metaKey: boolean;
638
  /** Whether alt key was pressed */
639
  altKey: boolean;
640
  /** Repeat count */
641
  repeat: boolean;
642
  /** Whether event is composing */
643
  isComposing: boolean;
644
  /** Target element */
645
  target: Element;
646
  /** Current target element */
647
  currentTarget: Element;
648
  /** Prevent default behavior */
649
  preventDefault(): void;
650
  /** Stop propagation */
651
  stopPropagation(): void;
652
  /** Continue propagation */
653
  continuePropagation(): void;
654
}
655

656
interface FocusEvent {
657
  /** Type of focus event */
658
  type: 'focus' | 'blur' | 'focusin' | 'focusout';
659
  /** Target element */
660
  target: Element;
661
  /** Related target element */
662
  relatedTarget: Element | null;
663
}
664

665
type DropOperation = 'copy' | 'link' | 'move' | 'cancel';
666

667
interface DragItem {
668
  /** MIME types for the item */
669
  [type: string]: string | (() => string);
670
}
671

672
interface DropTarget {
673
  /** Type of drop target */
674
  type: 'item' | 'folder' | 'root';
675
  /** Key of the target */
676
  key?: Key;
677
  /** Drop position relative to target */
678
  dropPosition?: 'before' | 'after' | 'on';
679
}
680

681
interface DragStartEvent {
682
  /** Type of event */
683
  type: 'dragstart';
684
  /** X coordinate */
685
  x: number;
686
  /** Y coordinate */
687
  y: number;
688
}
689

690
interface DragMoveEvent {
691
  /** Type of event */
692
  type: 'dragmove';
693
  /** X coordinate */
694
  x: number;
695
  /** Y coordinate */
696
  y: number;
697
  /** Delta X */
698
  deltaX: number;
699
  /** Delta Y */
700
  deltaY: number;
701
}
702

703
interface DragEndEvent {
704
  /** Type of event */
705
  type: 'dragend';
706
  /** X coordinate */
707
  x: number;
708
  /** Y coordinate */
709
  y: number;
710
  /** Drop operation performed */
711
  dropOperation: DropOperation;
712
  /** Whether operation was successful */
713
  isInternal: boolean;
714
}
715

716
interface DropEvent {
717
  /** Type of event */
718
  type: 'drop';
719
  /** X coordinate */
720
  x: number;
721
  /** Y coordinate */
722
  y: number;
723
  /** Drop operation */
724
  dropOperation: DropOperation;
725
  /** Dropped items */
726
  items: DropItem[];
727
  /** Drop target */
728
  target: DropTarget;
729
}
730
```