npm-react-aria

1
# Layout and Navigation
2

3
Components for organizing and navigating content including tabs, breadcrumbs, tables, trees, and other structural elements. All components provide proper keyboard navigation, screen reader support, and ARIA semantics.
4

5
## Capabilities
6

7
### Tabs
8

9
Provides tab interface behavior with keyboard navigation and content management.
10

11
```typescript { .api }
12
/**
13
 * Provides tab list behavior and accessibility
14
 * @param props - Tab list configuration
15
 * @param state - Tab list state
16
 * @param ref - Ref to the tab list element
17
 * @returns Tab list props and state
18
 */
19
function useTabList<T>(props: AriaTabListProps<T>, state: TabListState<T>, ref: RefObject<Element>): TabListAria;
20

21
/**
22
 * Provides individual tab behavior
23
 * @param props - Tab configuration
24
 * @param state - Tab list state
25
 * @param ref - Ref to the tab element
26
 * @returns Tab props and state
27
 */
28
function useTab(props: AriaTabProps, state: TabListState<T>, ref: RefObject<Element>): TabAria;
29

30
/**
31
 * Provides tab panel behavior for content areas
32
 * @param props - Tab panel configuration
33
 * @param state - Tab list state
34
 * @param ref - Ref to the panel element
35
 * @returns Tab panel props
36
 */
37
function useTabPanel(props: AriaTabPanelProps, state: TabListState<T>, ref: RefObject<Element>): TabPanelAria;
38

39
interface AriaTabListProps<T> extends AriaTabListOptions<T> {
40
  /** Items in the tab list */
41
  items?: Iterable<T>;
42
  /** Currently selected key */
43
  selectedKey?: Key | null;
44
  /** Default selected key (uncontrolled) */
45
  defaultSelectedKey?: Key | null;
46
  /** Handler called when selection changes */
47
  onSelectionChange?: (key: Key) => void;
48
  /** Orientation of the tab list */
49
  orientation?: Orientation;
50
  /** Whether tabs are disabled */
51
  isDisabled?: boolean;
52
  /** Keyboard activation mode */
53
  keyboardActivation?: 'automatic' | 'manual';
54
  /** Disabled keys */
55
  disabledKeys?: Iterable<Key>;
56
}
57

58
interface TabListAria {
59
  /** Props for the tab list element */
60
  tabListProps: DOMAttributes<Element>;
61
}
62

63
interface AriaTabProps {
64
  /** Key for the tab */
65
  key?: Key;
66
  /** Whether the tab is disabled */
67
  isDisabled?: boolean;
68
}
69

70
interface TabAria {
71
  /** Props for the tab element */
72
  tabProps: DOMAttributes<Element>;
73
  /** Whether the tab is selected */
74
  isSelected: boolean;
75
  /** Whether the tab is disabled */
76
  isDisabled: boolean;
77
  /** Whether the tab is pressed */
78
  isPressed: boolean;
79
}
80

81
interface AriaTabPanelProps {
82
  /** Key for the tab panel */
83
  key?: Key;
84
}
85

86
interface TabPanelAria {
87
  /** Props for the tab panel element */
88
  tabPanelProps: DOMAttributes<Element>;
89
}
90
```
91

92
### Breadcrumbs
93

94
Provides breadcrumb navigation behavior with proper accessibility and structure.
95

96
```typescript { .api }
97
/**
98
 * Provides breadcrumbs container behavior and accessibility
99
 * @param props - Breadcrumbs configuration
100
 * @param ref - Ref to the breadcrumbs element
101
 * @returns Breadcrumbs props
102
 */
103
function useBreadcrumbs(props: AriaBreadcrumbsProps, ref: RefObject<Element>): BreadcrumbsAria;
104

105
/**
106
 * Provides individual breadcrumb item behavior
107
 * @param props - Breadcrumb item configuration
108
 * @param ref - Ref to the breadcrumb element
109
 * @returns Breadcrumb item props
110
 */
111
function useBreadcrumbItem(props: AriaBreadcrumbItemProps, ref: RefObject<Element>): BreadcrumbItemAria;
112

113
interface AriaBreadcrumbsProps {
114
  /** Children breadcrumb items */
115
  children: ReactNode;
116
  /** Whether breadcrumbs are disabled */
117
  isDisabled?: boolean;
118
}
119

120
interface BreadcrumbsAria {
121
  /** Props for the breadcrumbs nav element */
122
  navProps: HTMLAttributes<HTMLElement>;
123
  /** Props for the breadcrumbs list element */
124
  listProps: HTMLAttributes<HTMLOListElement>;
125
}
126

127
interface AriaBreadcrumbItemProps {
128
  /** Children content */
129
  children: ReactNode;
130
  /** Whether this is the current page */
131
  isCurrent?: boolean;
132
  /** Whether the item is disabled */
133
  isDisabled?: boolean;
134
  /** Handler called when the item is activated */
135
  onAction?: () => void;
136
  /** Href for link behavior */
137
  href?: string;
138
  /** Target for link */
139
  target?: string;
140
  /** Rel for link */
141
  rel?: string;
142
}
143

144
interface BreadcrumbItemAria {
145
  /** Props for the breadcrumb item element */
146
  itemProps: HTMLAttributes<HTMLLIElement>;
147
  /** Props for the breadcrumb link element */
148
  linkProps: AnchorHTMLAttributes<HTMLAnchorElement> | ButtonHTMLAttributes<HTMLButtonElement>;
149
  /** Whether this is the current page */
150
  isCurrent: boolean;
151
  /** Whether the item is disabled */
152
  isDisabled: boolean;
153
}
154
```
155

156
### Table
157

158
Provides table behavior with selection, sorting, and keyboard navigation.
159

160
```typescript { .api }
161
/**
162
 * Provides table behavior and accessibility
163
 * @param props - Table configuration
164
 * @param state - Table state
165
 * @param ref - Ref to the table element
166
 * @returns Table props and state
167
 */
168
function useTable<T>(props: AriaTableProps<T>, state: TableState<T>, ref: RefObject<Element>): GridAria;
169

170
/**
171
 * Provides table row behavior
172
 * @param props - Table row configuration
173
 * @param state - Table state
174
 * @param ref - Ref to the row element
175
 * @returns Table row props and state
176
 */
177
function useTableRow<T>(props: GridRowProps<T>, state: TableState<T>, ref: RefObject<Element>): GridRowAria;
178

179
/**
180
 * Provides table cell behavior
181
 * @param props - Table cell configuration
182
 * @param state - Table state
183
 * @param ref - Ref to the cell element
184
 * @returns Table cell props
185
 */
186
function useTableCell(props: AriaTableCellProps, state: TableState<T>, ref: RefObject<Element>): TableCellAria;
187

188
/**
189
 * Provides table column header behavior with sorting
190
 * @param props - Column header configuration
191
 * @param state - Table state
192
 * @param ref - Ref to the header element
193
 * @returns Column header props and state
194
 */
195
function useTableColumnHeader<T>(props: AriaTableColumnHeaderProps, state: TableState<T>, ref: RefObject<Element>): TableColumnHeaderAria;
196

197
/**
198
 * Provides table row group behavior (thead, tbody, tfoot)
199
 * @param ref - Ref to the row group element
200
 * @returns Row group props
201
 */
202
function useTableRowGroup(ref: RefObject<Element>): TableHeaderRowAria;
203

204
/**
205
 * Provides table header row behavior
206
 * @param props - Header row configuration
207
 * @param state - Table state
208
 * @param ref - Ref to the header row element
209
 * @returns Header row props
210
 */
211
function useTableHeaderRow<T>(props: {}, state: TableState<T>, ref: RefObject<Element>): TableHeaderRowAria;
212

213
/**
214
 * Provides select all checkbox behavior for tables
215
 * @param props - Select all checkbox configuration
216
 * @param state - Table state
217
 * @param ref - Ref to the checkbox element
218
 * @returns Select all checkbox props
219
 */
220
function useTableSelectAllCheckbox<T>(props: AriaTableSelectionCheckboxProps, state: TableState<T>, ref: RefObject<Element>): TableSelectAllCheckboxAria;
221

222
/**
223
 * Provides selection checkbox behavior for table rows
224
 * @param props - Selection checkbox configuration
225
 * @param state - Table state
226
 * @param ref - Ref to the checkbox element
227
 * @returns Selection checkbox props
228
 */
229
function useTableSelectionCheckbox<T>(props: AriaTableSelectionCheckboxProps, state: TableState<T>, ref: RefObject<Element>): TableSelectionCheckboxAria;
230

231
/**
232
 * Provides column resize behavior for table columns
233
 * @param props - Column resize configuration
234
 * @param state - Table state
235
 * @param ref - Ref to the resize handle element
236
 * @returns Column resize props and state
237
 */
238
function useTableColumnResize<T>(props: AriaTableColumnResizeProps, state: TableState<T>, ref: RefObject<Element>): TableColumnResizeAria;
239

240
interface AriaTableProps<T> {
241
  /** Items in the table */
242
  items?: Iterable<T>;
243
  /** Selection mode */
244
  selectionMode?: SelectionMode;
245
  /** Selected keys */
246
  selectedKeys?: 'all' | Iterable<Key>;
247
  /** Default selected keys (uncontrolled) */
248
  defaultSelectedKeys?: 'all' | Iterable<Key>;
249
  /** Handler called when selection changes */
250
  onSelectionChange?: (keys: Selection) => void;
251
  /** Disabled keys */
252
  disabledKeys?: Iterable<Key>;
253
  /** Sort descriptor */
254
  sortDescriptor?: SortDescriptor;
255
  /** Handler called when sort changes */
256
  onSortChange?: (descriptor: SortDescriptor) => void;
257
  /** Handler called when a row is activated */
258
  onAction?: (key: Key) => void;
259
  /** Handler called on row expansion */
260
  onExpandedChange?: (keys: Set<Key>) => void;
261
  /** Whether rows can be resized */
262
  allowsResizing?: boolean;
263
  /** Whether column headers are sticky */
264
  stickyColumnHeaders?: boolean;
265
}
266

267
interface GridAria {
268
  /** Props for the table grid element */
269
  gridProps: DOMAttributes<Element>;
270
}
271
```
272

273
### Tree
274

275
Provides tree view behavior with hierarchical navigation and expansion.
276

277
```typescript { .api }
278
/**
279
 * Provides tree behavior and accessibility
280
 * @param props - Tree configuration
281
 * @param state - Tree state
282
 * @param ref - Ref to the tree element
283
 * @returns Tree props and state
284
 */
285
function useTree<T>(props: AriaTreeProps<T>, state: TreeState<T>, ref: RefObject<Element>): TreeAria;
286

287
/**
288
 * Provides tree item behavior with expansion and selection
289
 * @param props - Tree item configuration
290
 * @param state - Tree state
291
 * @param ref - Ref to the tree item element
292
 * @returns Tree item props and state
293
 */
294
function useTreeItem<T>(props: AriaTreeItemOptions<T>, state: TreeState<T>, ref: RefObject<Element>): TreeItemAria;
295

296
interface AriaTreeProps<T> extends TreeProps<T> {
297
  /** Items in the tree */
298
  items?: Iterable<T>;
299
  /** Selection mode */
300
  selectionMode?: SelectionMode;
301
  /** Selected keys */
302
  selectedKeys?: 'all' | Iterable<Key>;
303
  /** Default selected keys (uncontrolled) */
304
  defaultSelectedKeys?: 'all' | Iterable<Key>;
305
  /** Handler called when selection changes */
306
  onSelectionChange?: (keys: Selection) => void;
307
  /** Expanded keys */
308
  expandedKeys?: Iterable<Key>;
309
  /** Default expanded keys (uncontrolled) */
310
  defaultExpandedKeys?: Iterable<Key>;
311
  /** Handler called when expansion changes */
312
  onExpandedChange?: (keys: Set<Key>) => void;
313
  /** Disabled keys */
314
  disabledKeys?: Iterable<Key>;
315
  /** Handler called when an item is activated */
316
  onAction?: (key: Key) => void;
317
  /** Whether the tree is disabled */
318
  isDisabled?: boolean;
319
  /** Auto-focus behavior */
320
  autoFocus?: boolean | FocusStrategy;
321
  /** Whether focus should wrap */
322
  shouldFocusWrap?: boolean;
323
}
324

325
interface TreeAria {
326
  /** Props for the tree element */
327
  treeProps: DOMAttributes<Element>;
328
}
329

330
interface AriaTreeItemOptions<T> {
331
  /** Key for the tree item */
332
  key: Key;
333
  /** Whether the item is disabled */
334
  isDisabled?: boolean;
335
  /** Whether the item should be focused */
336
  shouldSelectOnPressUp?: boolean;
337
  /** Whether the item should use virtual focus */
338
  shouldUseVirtualFocus?: boolean;
339
  /** Ref for the tree item */
340
  ref?: RefObject<Element>;
341
}
342

343
interface TreeItemAria {
344
  /** Props for the tree item element */
345
  rowProps: DOMAttributes<Element>;
346
  /** Props for the tree item content */
347
  gridCellProps: DOMAttributes<Element>;
348
  /** Props for the expand button */
349
  buttonProps: ButtonHTMLAttributes<HTMLButtonElement>;
350
  /** Props for the checkbox */
351
  checkboxProps: InputHTMLAttributes<HTMLInputElement>;
352
  /** Whether the item is selected */
353
  isSelected: boolean;
354
  /** Whether the item is expanded */
355
  isExpanded: boolean;
356
  /** Whether the item is disabled */
357
  isDisabled: boolean;
358
  /** Whether the item is pressed */
359
  isPressed: boolean;
360
  /** Level of the item in the tree */
361
  level: number;
362
  /** Whether the item has child items */
363
  hasChildRows: boolean;
364
}
365
```
366

367
### Link
368

369
Provides link behavior with proper accessibility and routing integration.
370

371
```typescript { .api }
372
/**
373
 * Provides link behavior and accessibility
374
 * @param props - Link configuration
375
 * @param ref - Ref to the link element
376
 * @returns Link props and state
377
 */
378
function useLink(props: AriaLinkOptions, ref: RefObject<Element>): LinkAria;
379

380
interface AriaLinkOptions {
381
  /** Whether the link is disabled */
382
  isDisabled?: boolean;
383
  /** Handler called when the link is activated */
384
  onPress?: (e: PressEvent) => void;
385
  /** Element type to render as */
386
  elementType?: React.ElementType;
387
}
388

389
interface LinkAria {
390
  /** Props for the link element */
391
  linkProps: AnchorHTMLAttributes<HTMLAnchorElement>;
392
  /** Whether the link is pressed */
393
  isPressed: boolean;
394
}
395
```
396

397
### Tags
398

399
Provides tag group behavior for managing collections of tags or chips.
400

401
```typescript { .api }
402
/**
403
 * Provides tag group behavior and accessibility
404
 * @param props - Tag group configuration
405
 * @param state - Tag group state
406
 * @param ref - Ref to the tag group element
407
 * @returns Tag group props and state
408
 */
409
function useTagGroup<T>(props: AriaTagGroupProps<T>, state: ListState<T>, ref: RefObject<Element>): TagGroupAria;
410

411
/**
412
 * Provides individual tag behavior
413
 * @param props - Tag configuration
414
 * @param state - Tag group state
415
 * @param ref - Ref to the tag element
416
 * @returns Tag props and state
417
 */
418
function useTag<T>(props: AriaTagProps, state: ListState<T>, ref: RefObject<Element>): TagAria;
419

420
interface AriaTagGroupProps<T> {
421
  /** Items in the tag group */
422
  items?: Iterable<T>;
423
  /** Selected keys */
424
  selectedKeys?: 'all' | Iterable<Key>;
425
  /** Default selected keys (uncontrolled) */
426
  defaultSelectedKeys?: 'all' | Iterable<Key>;
427
  /** Handler called when selection changes */
428
  onSelectionChange?: (keys: Selection) => void;
429
  /** Handler called when a tag is removed */
430
  onRemove?: (keys: Set<Key>) => void;
431
  /** Whether tags can be removed */
432
  allowsRemoving?: boolean;
433
  /** Whether the tag group is disabled */
434
  isDisabled?: boolean;
435
  /** Label for the tag group */
436
  label?: ReactNode;
437
  /** Description for the tag group */
438
  description?: ReactNode;
439
  /** Error message for the tag group */
440
  errorMessage?: ReactNode;
441
}
442

443
interface TagGroupAria {
444
  /** Props for the tag group element */
445
  gridProps: DOMAttributes<Element>;
446
  /** Props for the label element */
447
  labelProps: DOMAttributes<Element>;
448
  /** Props for the description element */
449
  descriptionProps: DOMAttributes<Element>;
450
  /** Props for the error message element */
451
  errorMessageProps: DOMAttributes<Element>;
452
}
453

454
interface AriaTagProps {
455
  /** Key for the tag */
456
  key?: Key;
457
  /** Whether the tag is disabled */
458
  isDisabled?: boolean;
459
  /** Text content of the tag */
460
  textContent?: string;
461
  /** Whether the tag can be removed */
462
  allowsRemoving?: boolean;
463
}
464

465
interface TagAria {
466
  /** Props for the tag row element */
467
  rowProps: DOMAttributes<Element>;
468
  /** Props for the tag content element */
469
  gridCellProps: DOMAttributes<Element>;
470
  /** Props for the remove button */
471
  removeButtonProps: ButtonHTMLAttributes<HTMLButtonElement>;
472
  /** Props for the tag description */
473
  descriptionProps: DOMAttributes<Element>;
474
  /** Whether the tag is selected */
475
  isSelected: boolean;
476
  /** Whether the tag is disabled */
477
  isDisabled: boolean;
478
  /** Whether the tag is pressed */
479
  isPressed: boolean;
480
  /** Whether the remove button is pressed */
481
  isRemoveButtonPressed: boolean;
482
  /** Allow removing the tag */
483
  allowsRemoving: boolean;
484
}
485
```
486

487
### Separator
488

489
Provides separator element behavior for dividing content sections.
490

491
```typescript { .api }
492
/**
493
 * Provides separator behavior and accessibility
494
 * @param props - Separator configuration
495
 * @param ref - Ref to the separator element
496
 * @returns Separator props
497
 */
498
function useSeparator(props: SeparatorProps, ref: RefObject<Element>): SeparatorAria;
499

500
interface SeparatorProps {
501
  /** Orientation of the separator */
502
  orientation?: Orientation;
503
  /** Element type to render */
504
  elementType?: string;
505
}
506

507
interface SeparatorAria {
508
  /** Props for the separator element */
509
  separatorProps: DOMAttributes<Element>;
510
}
511
```
512

513
### Landmark
514

515
Provides landmark region behavior for page structure and navigation.
516

517
```typescript { .api }
518
/**
519
 * Provides landmark behavior and accessibility
520
 * @param props - Landmark configuration
521
 * @param ref - Ref to the landmark element
522
 * @returns Landmark props and controller
523
 */
524
function useLandmark(props: AriaLandmarkProps, ref: RefObject<Element>): LandmarkAria;
525

526
interface AriaLandmarkProps {
527
  /** ARIA landmark role */
528
  role?: AriaLandmarkRole;
529
  /** Accessible name for the landmark */
530
  'aria-label'?: string;
531
  /** ID of element that labels the landmark */
532
  'aria-labelledby'?: string;
533
}
534

535
interface LandmarkAria {
536
  /** Props for the landmark element */
537
  landmarkProps: DOMAttributes<Element>;
538
  /** Landmark controller for managing focus */
539
  landmarkController: LandmarkController;
540
}
541

542
type AriaLandmarkRole = 
543
  | 'banner'
544
  | 'complementary'
545
  | 'contentinfo'
546
  | 'form'
547
  | 'main'
548
  | 'navigation'
549
  | 'region'
550
  | 'search';
551

552
interface LandmarkController {
553
  /** Navigate to the next landmark */
554
  nextLandmark(): void;
555
  /** Navigate to the previous landmark */
556
  previousLandmark(): void;
557
  /** Get all landmarks on the page */
558
  getLandmarks(): Element[];
559
}
560
```
561

562
## Types
563

564
```typescript { .api }
565
interface TabListState<T> {
566
  /** Collection of tab items */
567
  collection: Collection<Node<T>>;
568
  /** Currently selected key */
569
  selectedKey: Key | null;
570
  /** Set the selected key */
571
  setSelectedKey(key: Key): void;
572
  /** Selected item */
573
  selectedItem: Node<T> | null;
574
}
575

576
interface TableState<T> {
577
  /** Collection of table items */
578
  collection: Collection<Node<T>>;
579
  /** Set of selected keys */
580
  selectedKeys: Selection;
581
  /** Set the selected keys */
582
  setSelectedKeys(keys: Selection): void;
583
  /** Sort descriptor */
584
  sortDescriptor: SortDescriptor | null;
585
  /** Set the sort descriptor */
586
  setSortDescriptor(descriptor: SortDescriptor): void;
587
  /** Set of expanded keys */
588
  expandedKeys: Set<Key>;
589
  /** Toggle expansion of a key */
590
  toggleExpanded(key: Key): void;
591
}
592

593
interface TreeState<T> {
594
  /** Collection of tree items */
595
  collection: Collection<Node<T>>;
596
  /** Set of selected keys */
597
  selectedKeys: Selection;
598
  /** Set the selected keys */
599
  setSelectedKeys(keys: Selection): void;
600
  /** Set of expanded keys */
601
  expandedKeys: Set<Key>;
602
  /** Toggle expansion of a key */
603
  toggleExpanded(key: Key): void;
604
  /** Currently focused key */
605
  focusedKey: Key | null;
606
  /** Set the focused key */
607
  setFocusedKey(key: Key): void;
608
}
609

610
interface SortDescriptor {
611
  /** Column key to sort by */
612
  column: Key;
613
  /** Sort direction */
614
  direction: 'ascending' | 'descending';
615
}
616
```