0
# Selection Controls
1

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

4
## Capabilities
5

6
### ListBox
7

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

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

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

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

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

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

78
### ComboBox
79

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

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

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

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

151
### Select
152

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

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

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

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

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

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

225
### Menu
226

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

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

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

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

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

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

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

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

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

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

311
### GridList
312

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

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

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

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

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

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

370
### Keyboard Delegates
371

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

394
## Types
395

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

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

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

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

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

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