npm-react-aria

1
# Selection Controls
2

3
Components for selecting from lists of options, including listboxes, comboboxes, menus, and select dropdowns. All selection controls provide keyboard navigation, screen reader support, and proper ARIA semantics.
4

5
## Capabilities
6

7
### ListBox
8

9
Provides listbox behavior for selecting from a list of options with keyboard navigation and multi-selection support.
10

11
```typescript { .api }
12
/**
13
 * Provides listbox behavior and accessibility
14
 * @param props - Listbox configuration
15
 * @param state - Selection state management
16
 * @param ref - Ref to the listbox element
17
 * @returns Listbox props and state
18
 */
19
function useListBox<T>(props: AriaListBoxProps<T>, state: ListState<T>, ref: RefObject<Element>): ListBoxAria;
20

21
/**
22
 * Provides listbox section behavior for grouping options
23
 * @param props - Section configuration
24
 * @param ref - Ref to the section element
25
 * @returns Section props
26
 */
27
function useListBoxSection<T>(props: AriaListBoxSectionProps<T>, ref: RefObject<Element>): ListBoxSectionAria;
28

29
/**
30
 * Provides individual option behavior within a listbox
31
 * @param props - Option configuration
32
 * @param state - Listbox state
33
 * @param ref - Ref to the option element
34
 * @returns Option props and state
35
 */
36
function useOption<T>(props: AriaOptionProps, state: ListState<T>, ref: RefObject<Element>): OptionAria;
37

38
interface AriaListBoxProps<T> {
39
  /** Item objects in the collection */
40
  items?: Iterable<T>;
41
  /** Selection mode */
42
  selectionMode?: 'none' | 'single' | 'multiple';
43
  /** Disable selection */
44
  disallowEmptySelection?: boolean;
45
  /** Currently selected keys */
46
  selectedKeys?: 'all' | Iterable<Key>;
47
  /** Default selected keys (uncontrolled) */
48
  defaultSelectedKeys?: 'all' | Iterable<Key>;
49
  /** Handler called when selection changes */
50
  onSelectionChange?: (keys: Selection) => void;
51
  /** Currently focused key */
52
  focusedKey?: Key;
53
  /** Default focused key (uncontrolled) */
54
  defaultFocusedKey?: Key;
55
  /** Handler called when focus changes */
56
  onFocusChange?: (key: Key) => void;
57
  /** Whether the listbox is disabled */
58
  isDisabled?: boolean;
59
  /** Handler called when an option is activated */
60
  onAction?: (key: Key) => void;
61
  /** Handler called when scrolling should occur */
62
  onScroll?: (e: UIEvent<Element>) => void;
63
  /** Whether to auto-focus the listbox */
64
  autoFocus?: boolean | FocusStrategy;
65
  /** Handler called when the listbox should scroll to an item */
66
  shouldFocusWrap?: boolean;
67
  /** Whether virtualized scrolling is used */
68
  isVirtualized?: boolean;
69
  /** Layout delegate for virtualized scrolling */
70
  layoutDelegate?: LayoutDelegate;
71
}
72

73
interface ListBoxAria {
74
  /** Props for the listbox element */
75
  listBoxProps: DOMAttributes<Element>;
76
}
77
```
78

79
### ComboBox
80

81
Provides combobox behavior combining a text input with a listbox popup for autocomplete functionality.
82

83
```typescript { .api }
84
/**
85
 * Provides combobox behavior and accessibility
86
 * @param props - Combobox configuration
87
 * @param state - Combobox state management
88
 * @param ref - Ref to the combobox element
89
 * @returns Combobox props and state
90
 */
91
function useComboBox<T>(props: AriaComboBoxProps<T>, state: ComboBoxState<T>, ref: RefObject<Element>): ComboBoxAria;
92

93
interface AriaComboBoxProps<T> extends AriaComboBoxOptions<T> {
94
  /** Current input value */
95
  inputValue?: string;
96
  /** Default input value (uncontrolled) */
97
  defaultInputValue?: string;
98
  /** Handler called when input value changes */
99
  onInputChange?: (value: string) => void;
100
  /** Whether the popup is open */
101
  isOpen?: boolean;
102
  /** Default open state (uncontrolled) */
103
  defaultOpen?: boolean;
104
  /** Handler called when open state changes */
105
  onOpenChange?: (isOpen: boolean) => void;
106
  /** Currently selected key */
107
  selectedKey?: Key | null;
108
  /** Default selected key (uncontrolled) */
109
  defaultSelectedKey?: Key | null;
110
  /** Handler called when selection changes */
111
  onSelectionChange?: (key: Key | null) => void;
112
  /** Disable selection */
113
  disallowEmptySelection?: boolean;
114
  /** Items in the collection */
115
  items?: Iterable<T>;
116
  /** Function to get display text for an item */
117
  itemText?: (item: T) => string;
118
  /** Handler called when an item is selected */
119
  onAction?: (key: Key) => void;
120
  /** Whether the combobox allows custom values */
121
  allowsCustomValue?: boolean;
122
  /** Menu trigger behavior */
123
  menuTrigger?: 'focus' | 'input' | 'manual';
124
  /** Whether the combobox is disabled */
125
  isDisabled?: boolean;
126
  /** Whether the combobox is read-only */
127
  isReadOnly?: boolean;
128
  /** Whether the combobox is required */
129
  isRequired?: boolean;
130
  /** Validation state */
131
  validationState?: 'valid' | 'invalid';
132
  /** Auto-complete behavior */
133
  completionMode?: 'complete' | 'list' | 'both';
134
}
135

136
interface ComboBoxAria {
137
  /** Props for the combobox label */
138
  labelProps: DOMAttributes<Element>;
139
  /** Props for the text input element */
140
  inputProps: InputHTMLAttributes<HTMLInputElement>;
141
  /** Props for the listbox element */
142
  listBoxProps: DOMAttributes<Element>;
143
  /** Props for the popup button */
144
  buttonProps: ButtonHTMLAttributes<HTMLButtonElement>;
145
  /** Props for the description element */
146
  descriptionProps: DOMAttributes<Element>;
147
  /** Props for the error message element */
148
  errorMessageProps: DOMAttributes<Element>;
149
}
150
```
151

152
### Select
153

154
Provides select dropdown behavior with keyboard navigation and accessibility.
155

156
```typescript { .api }
157
/**
158
 * Provides select behavior and accessibility
159
 * @param props - Select configuration
160
 * @param state - Select state management
161
 * @param ref - Ref to the select element
162
 * @returns Select props and state
163
 */
164
function useSelect<T>(props: AriaSelectProps<T>, state: SelectState<T>, ref: RefObject<Element>): SelectAria;
165

166
/**
167
 * Provides hidden select behavior for form integration
168
 * @param props - Hidden select configuration
169
 * @param ref - Ref to the select element
170
 * @returns Select element properties
171
 */
172
function useHiddenSelect<T>(props: AriaHiddenSelectProps, ref: RefObject<HTMLSelectElement>): HiddenSelectProps;
173

174
/**
175
 * Hidden select component for form integration
176
 * @param props - Hidden select configuration
177
 * @returns Hidden select element
178
 */
179
function HiddenSelect<T>(props: HiddenSelectProps): JSX.Element;
180

181
interface AriaSelectProps<T> extends AriaSelectOptions<T> {
182
  /** Currently selected key */
183
  selectedKey?: Key | null;
184
  /** Default selected key (uncontrolled) */
185
  defaultSelectedKey?: Key | null;
186
  /** Handler called when selection changes */
187
  onSelectionChange?: (key: Key | null) => void;
188
  /** Whether the select is open */
189
  isOpen?: boolean;
190
  /** Default open state (uncontrolled) */
191
  defaultOpen?: boolean;
192
  /** Handler called when open state changes */
193
  onOpenChange?: (isOpen: boolean) => void;
194
  /** Items in the collection */
195
  items?: Iterable<T>;
196
  /** Disable empty selection */
197
  disallowEmptySelection?: boolean;
198
  /** Whether the select is disabled */
199
  isDisabled?: boolean;
200
  /** Whether the select is required */
201
  isRequired?: boolean;
202
  /** Validation state */
203
  validationState?: 'valid' | 'invalid';
204
  /** Auto-focus behavior */
205
  autoFocus?: boolean;
206
  /** Name for form integration */
207
  name?: string;
208
}
209

210
interface SelectAria {
211
  /** Props for the select label */
212
  labelProps: DOMAttributes<Element>;
213
  /** Props for the trigger button */
214
  triggerProps: ButtonHTMLAttributes<HTMLButtonElement>;
215
  /** Props for the value element */
216
  valueProps: DOMAttributes<Element>;
217
  /** Props for the listbox */
218
  listBoxProps: DOMAttributes<Element>;
219
  /** Props for the description element */
220
  descriptionProps: DOMAttributes<Element>;
221
  /** Props for the error message element */
222
  errorMessageProps: DOMAttributes<Element>;
223
}
224
```
225

226
### Menu
227

228
Provides menu behavior with hierarchical navigation and action handling.
229

230
```typescript { .api }
231
/**
232
 * Provides menu behavior and accessibility
233
 * @param props - Menu configuration
234
 * @param state - Menu state management
235
 * @param ref - Ref to the menu element
236
 * @returns Menu props and state
237
 */
238
function useMenu<T>(props: AriaMenuProps<T>, state: TreeState<T>, ref: RefObject<Element>): MenuAria;
239

240
/**
241
 * Provides menu trigger behavior for opening menus
242
 * @param props - Menu trigger configuration
243
 * @param state - Menu trigger state
244
 * @param ref - Ref to the trigger element
245
 * @returns Menu trigger props
246
 */
247
function useMenuTrigger<T>(props: AriaMenuTriggerProps, state: MenuTriggerState, ref: RefObject<Element>): MenuTriggerAria;
248

249
/**
250
 * Provides individual menu item behavior
251
 * @param props - Menu item configuration
252
 * @param state - Menu state
253
 * @param ref - Ref to the menu item element
254
 * @returns Menu item props and state
255
 */
256
function useMenuItem<T>(props: AriaMenuItemProps, state: TreeState<T>, ref: RefObject<Element>): MenuItemAria;
257

258
/**
259
 * Provides menu section behavior for grouping items
260
 * @param props - Section configuration
261
 * @param ref - Ref to the section element
262
 * @returns Section props
263
 */
264
function useMenuSection<T>(props: AriaMenuSectionProps<T>, ref: RefObject<Element>): MenuSectionAria;
265

266
/**
267
 * Provides submenu trigger behavior
268
 * @param props - Submenu trigger configuration
269
 * @param state - Menu state
270
 * @param ref - Ref to the trigger element
271
 * @returns Submenu trigger props
272
 */
273
function useSubmenuTrigger<T>(props: AriaSubmenuTriggerProps, state: TreeState<T>, ref: RefObject<Element>): SubmenuTriggerAria;
274

275
interface AriaMenuProps<T> extends AriaMenuOptions<T> {
276
  /** Items in the menu */
277
  items?: Iterable<T>;
278
  /** Disabled keys */
279
  disabledKeys?: Iterable<Key>;
280
  /** Handler called when an item is selected */
281
  onAction?: (key: Key) => void;
282
  /** Handler called when menu should close */
283
  onClose?: () => void;
284
  /** Auto-focus behavior */
285
  autoFocus?: boolean | FocusStrategy;
286
  /** Whether focus should wrap */
287
  shouldFocusWrap?: boolean;
288
}
289

290
interface MenuAria {
291
  /** Props for the menu element */
292
  menuProps: DOMAttributes<Element>;
293
}
294

295
interface AriaMenuTriggerProps {
296
  /** Type of menu trigger */
297
  type?: 'menu' | 'listbox' | 'tree' | 'grid' | 'dialog';
298
  /** Whether the menu is disabled */
299
  isDisabled?: boolean;
300
  /** Trigger on which events */
301
  trigger?: 'press' | 'longPress';
302
}
303

304
interface MenuTriggerAria {
305
  /** Props for the menu trigger element */
306
  menuTriggerProps: ButtonHTMLAttributes<HTMLButtonElement>;
307
  /** Props for the menu element */
308
  menuProps: DOMAttributes<Element>;
309
}
310
```
311

312
### GridList
313

314
Provides grid list behavior for two-dimensional selection and navigation.
315

316
```typescript { .api }
317
/**
318
 * Provides grid list behavior and accessibility
319
 * @param props - Grid list configuration
320
 * @param state - Grid list state
321
 * @param ref - Ref to the grid element
322
 * @returns Grid list props and state
323
 */
324
function useGridList<T>(props: AriaGridListProps<T>, state: ListState<T>, ref: RefObject<Element>): GridListAria;
325

326
/**
327
 * Provides grid list item behavior
328
 * @param props - Grid list item configuration
329
 * @param state - Grid list state
330
 * @param ref - Ref to the item element
331
 * @returns Grid list item props and state
332
 */
333
function useGridListItem<T>(props: AriaGridListItemOptions<T>, state: ListState<T>, ref: RefObject<Element>): GridListItemAria;
334

335
/**
336
 * Provides selection checkbox behavior for grid list items
337
 * @param props - Selection checkbox configuration
338
 * @param state - Grid list state
339
 * @param ref - Ref to the checkbox element
340
 * @returns Selection checkbox props
341
 */
342
function useGridListSelectionCheckbox<T>(props: AriaGridSelectionCheckboxProps, state: ListState<T>, ref: RefObject<Element>): GridSelectionCheckboxAria;
343

344
interface AriaGridListProps<T> extends AriaGridListOptions<T> {
345
  /** Items in the grid */
346
  items?: Iterable<T>;
347
  /** Selection mode */
348
  selectionMode?: 'none' | 'single' | 'multiple';
349
  /** Selected keys */
350
  selectedKeys?: 'all' | Iterable<Key>;
351
  /** Default selected keys (uncontrolled) */
352
  defaultSelectedKeys?: 'all' | Iterable<Key>;
353
  /** Handler called when selection changes */
354
  onSelectionChange?: (keys: Selection) => void;
355
  /** Disabled keys */
356
  disabledKeys?: Iterable<Key>;
357
  /** Handler called when an item is activated */
358
  onAction?: (key: Key) => void;
359
  /** Whether the grid is disabled */
360
  isDisabled?: boolean;
361
  /** Auto-focus behavior */
362
  autoFocus?: boolean | FocusStrategy;
363
}
364

365
interface GridListAria {
366
  /** Props for the grid list element */
367
  gridProps: DOMAttributes<Element>;
368
}
369
```
370

371
### Keyboard Delegates
372

373
```typescript { .api }
374
/**
375
 * Keyboard navigation delegate for list components
376
 */
377
class ListKeyboardDelegate {
378
  /** Get the key above the current key */
379
  getKeyAbove(key: Key): Key | null;
380
  /** Get the key below the current key */
381
  getKeyBelow(key: Key): Key | null;
382
  /** Get the key to the left of the current key */
383
  getKeyLeftOf(key: Key): Key | null;
384
  /** Get the key to the right of the current key */
385
  getKeyRightOf(key: Key): Key | null;
386
  /** Get the first key */
387
  getFirstKey(): Key | null;
388
  /** Get the last key */
389
  getLastKey(): Key | null;
390
  /** Get the key for a character */
391
  getKeyForSearch(search: string, fromKey?: Key): Key | null;
392
}
393
```
394

395
## Types
396

397
```typescript { .api }
398
type Selection = 'all' | Set<Key>;
399

400
type SelectionMode = 'none' | 'single' | 'multiple';
401

402
type FocusStrategy = 'first' | 'last';
403

404
interface ListState<T> {
405
  /** Collection of items */
406
  collection: Collection<Node<T>>;
407
  /** Set of selected keys */
408
  selectedKeys: Selection;
409
  /** Currently focused key */
410
  focusedKey: Key | null;
411
  /** Whether the collection allows empty selection */
412
  disallowEmptySelection: boolean;
413
  /** Selection mode */
414
  selectionMode: SelectionMode;
415
  /** Set of disabled keys */
416
  disabledKeys: Set<Key>;
417
  /** Select an item */
418
  setSelectedKeys(keys: Selection): void;
419
  /** Toggle selection of an item */
420
  toggleSelection(key: Key): void;
421
  /** Replace selection with a single item */
422
  replaceSelection(key: Key): void;
423
  /** Select all items */
424
  selectAll(): void;
425
  /** Clear all selection */
426
  clearSelection(): void;
427
  /** Set the focused key */
428
  setFocusedKey(key: Key): void;
429
}
430

431
interface ComboBoxState<T> extends ListState<T> {
432
  /** Current input value */
433
  inputValue: string;
434
  /** Set the input value */
435
  setInputValue(value: string): void;
436
  /** Currently selected item */
437
  selectedItem: Node<T> | null;
438
  /** Currently selected key */
439
  selectedKey: Key | null;
440
  /** Set the selected key */
441
  setSelectedKey(key: Key | null): void;
442
  /** Whether the popup is open */
443
  isOpen: boolean;
444
  /** Set the open state */
445
  setOpen(isOpen: boolean): void;
446
  /** Toggle the open state */
447
  toggle(): void;
448
  /** Open the popup */
449
  open(): void;
450
  /** Close the popup */
451
  close(): void;
452
  /** Commit the current input value */
453
  commit(): void;
454
  /** Revert to the selected item's text */
455
  revert(): void;
456
}
457

458
interface SelectState<T> {
459
  /** Whether the select is open */
460
  isOpen: boolean;
461
  /** Set the open state */
462
  setOpen(isOpen: boolean): void;
463
  /** Currently selected key */
464
  selectedKey: Key | null;
465
  /** Set the selected key */
466
  setSelectedKey(key: Key | null): void;
467
  /** Currently selected item */
468
  selectedItem: Node<T> | null;
469
  /** Collection of items */
470
  collection: Collection<Node<T>>;
471
  /** Toggle the open state */
472
  toggle(): void;
473
  /** Open the select */
474
  open(): void;
475
  /** Close the select */
476
  close(): void;
477
}
478
```