0
# Layout and Navigation
1
2
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.
3
4
## Capabilities
5
6
### Tabs
7
8
Provides tab interface behavior with keyboard navigation and content management.
9
10
```typescript { .api }
11
/**
12
* Provides tab list behavior and accessibility
13
* @param props - Tab list configuration
14
* @param state - Tab list state
15
* @param ref - Ref to the tab list element
16
* @returns Tab list props and state
17
*/
18
function useTabList<T>(props: AriaTabListProps<T>, state: TabListState<T>, ref: RefObject<Element>): TabListAria;
19
20
/**
21
* Provides individual tab behavior
22
* @param props - Tab configuration
23
* @param state - Tab list state
24
* @param ref - Ref to the tab element
25
* @returns Tab props and state
26
*/
27
function useTab(props: AriaTabProps, state: TabListState<T>, ref: RefObject<Element>): TabAria;
28
29
/**
30
* Provides tab panel behavior for content areas
31
* @param props - Tab panel configuration
32
* @param state - Tab list state
33
* @param ref - Ref to the panel element
34
* @returns Tab panel props
35
*/
36
function useTabPanel(props: AriaTabPanelProps, state: TabListState<T>, ref: RefObject<Element>): TabPanelAria;
37
38
interface AriaTabListProps<T> extends AriaTabListOptions<T> {
39
/** Items in the tab list */
40
items?: Iterable<T>;
41
/** Currently selected key */
42
selectedKey?: Key | null;
43
/** Default selected key (uncontrolled) */
44
defaultSelectedKey?: Key | null;
45
/** Handler called when selection changes */
46
onSelectionChange?: (key: Key) => void;
47
/** Orientation of the tab list */
48
orientation?: Orientation;
49
/** Whether tabs are disabled */
50
isDisabled?: boolean;
51
/** Keyboard activation mode */
52
keyboardActivation?: 'automatic' | 'manual';
53
/** Disabled keys */
54
disabledKeys?: Iterable<Key>;
55
}
56
57
interface TabListAria {
58
/** Props for the tab list element */
59
tabListProps: DOMAttributes<Element>;
60
}
61
62
interface AriaTabProps {
63
/** Key for the tab */
64
key?: Key;
65
/** Whether the tab is disabled */
66
isDisabled?: boolean;
67
}
68
69
interface TabAria {
70
/** Props for the tab element */
71
tabProps: DOMAttributes<Element>;
72
/** Whether the tab is selected */
73
isSelected: boolean;
74
/** Whether the tab is disabled */
75
isDisabled: boolean;
76
/** Whether the tab is pressed */
77
isPressed: boolean;
78
}
79
80
interface AriaTabPanelProps {
81
/** Key for the tab panel */
82
key?: Key;
83
}
84
85
interface TabPanelAria {
86
/** Props for the tab panel element */
87
tabPanelProps: DOMAttributes<Element>;
88
}
89
```
90
91
### Breadcrumbs
92
93
Provides breadcrumb navigation behavior with proper accessibility and structure.
94
95
```typescript { .api }
96
/**
97
* Provides breadcrumbs container behavior and accessibility
98
* @param props - Breadcrumbs configuration
99
* @param ref - Ref to the breadcrumbs element
100
* @returns Breadcrumbs props
101
*/
102
function useBreadcrumbs(props: AriaBreadcrumbsProps, ref: RefObject<Element>): BreadcrumbsAria;
103
104
/**
105
* Provides individual breadcrumb item behavior
106
* @param props - Breadcrumb item configuration
107
* @param ref - Ref to the breadcrumb element
108
* @returns Breadcrumb item props
109
*/
110
function useBreadcrumbItem(props: AriaBreadcrumbItemProps, ref: RefObject<Element>): BreadcrumbItemAria;
111
112
interface AriaBreadcrumbsProps {
113
/** Children breadcrumb items */
114
children: ReactNode;
115
/** Whether breadcrumbs are disabled */
116
isDisabled?: boolean;
117
}
118
119
interface BreadcrumbsAria {
120
/** Props for the breadcrumbs nav element */
121
navProps: HTMLAttributes<HTMLElement>;
122
/** Props for the breadcrumbs list element */
123
listProps: HTMLAttributes<HTMLOListElement>;
124
}
125
126
interface AriaBreadcrumbItemProps {
127
/** Children content */
128
children: ReactNode;
129
/** Whether this is the current page */
130
isCurrent?: boolean;
131
/** Whether the item is disabled */
132
isDisabled?: boolean;
133
/** Handler called when the item is activated */
134
onAction?: () => void;
135
/** Href for link behavior */
136
href?: string;
137
/** Target for link */
138
target?: string;
139
/** Rel for link */
140
rel?: string;
141
}
142
143
interface BreadcrumbItemAria {
144
/** Props for the breadcrumb item element */
145
itemProps: HTMLAttributes<HTMLLIElement>;
146
/** Props for the breadcrumb link element */
147
linkProps: AnchorHTMLAttributes<HTMLAnchorElement> | ButtonHTMLAttributes<HTMLButtonElement>;
148
/** Whether this is the current page */
149
isCurrent: boolean;
150
/** Whether the item is disabled */
151
isDisabled: boolean;
152
}
153
```
154
155
### Table
156
157
Provides table behavior with selection, sorting, and keyboard navigation.
158
159
```typescript { .api }
160
/**
161
* Provides table behavior and accessibility
162
* @param props - Table configuration
163
* @param state - Table state
164
* @param ref - Ref to the table element
165
* @returns Table props and state
166
*/
167
function useTable<T>(props: AriaTableProps<T>, state: TableState<T>, ref: RefObject<Element>): GridAria;
168
169
/**
170
* Provides table row behavior
171
* @param props - Table row configuration
172
* @param state - Table state
173
* @param ref - Ref to the row element
174
* @returns Table row props and state
175
*/
176
function useTableRow<T>(props: GridRowProps<T>, state: TableState<T>, ref: RefObject<Element>): GridRowAria;
177
178
/**
179
* Provides table cell behavior
180
* @param props - Table cell configuration
181
* @param state - Table state
182
* @param ref - Ref to the cell element
183
* @returns Table cell props
184
*/
185
function useTableCell(props: AriaTableCellProps, state: TableState<T>, ref: RefObject<Element>): TableCellAria;
186
187
/**
188
* Provides table column header behavior with sorting
189
* @param props - Column header configuration
190
* @param state - Table state
191
* @param ref - Ref to the header element
192
* @returns Column header props and state
193
*/
194
function useTableColumnHeader<T>(props: AriaTableColumnHeaderProps, state: TableState<T>, ref: RefObject<Element>): TableColumnHeaderAria;
195
196
/**
197
* Provides table row group behavior (thead, tbody, tfoot)
198
* @param ref - Ref to the row group element
199
* @returns Row group props
200
*/
201
function useTableRowGroup(ref: RefObject<Element>): TableHeaderRowAria;
202
203
/**
204
* Provides table header row behavior
205
* @param props - Header row configuration
206
* @param state - Table state
207
* @param ref - Ref to the header row element
208
* @returns Header row props
209
*/
210
function useTableHeaderRow<T>(props: {}, state: TableState<T>, ref: RefObject<Element>): TableHeaderRowAria;
211
212
/**
213
* Provides select all checkbox behavior for tables
214
* @param props - Select all checkbox configuration
215
* @param state - Table state
216
* @param ref - Ref to the checkbox element
217
* @returns Select all checkbox props
218
*/
219
function useTableSelectAllCheckbox<T>(props: AriaTableSelectionCheckboxProps, state: TableState<T>, ref: RefObject<Element>): TableSelectAllCheckboxAria;
220
221
/**
222
* Provides selection checkbox behavior for table rows
223
* @param props - Selection checkbox configuration
224
* @param state - Table state
225
* @param ref - Ref to the checkbox element
226
* @returns Selection checkbox props
227
*/
228
function useTableSelectionCheckbox<T>(props: AriaTableSelectionCheckboxProps, state: TableState<T>, ref: RefObject<Element>): TableSelectionCheckboxAria;
229
230
/**
231
* Provides column resize behavior for table columns
232
* @param props - Column resize configuration
233
* @param state - Table state
234
* @param ref - Ref to the resize handle element
235
* @returns Column resize props and state
236
*/
237
function useTableColumnResize<T>(props: AriaTableColumnResizeProps, state: TableState<T>, ref: RefObject<Element>): TableColumnResizeAria;
238
239
interface AriaTableProps<T> {
240
/** Items in the table */
241
items?: Iterable<T>;
242
/** Selection mode */
243
selectionMode?: SelectionMode;
244
/** Selected keys */
245
selectedKeys?: 'all' | Iterable<Key>;
246
/** Default selected keys (uncontrolled) */
247
defaultSelectedKeys?: 'all' | Iterable<Key>;
248
/** Handler called when selection changes */
249
onSelectionChange?: (keys: Selection) => void;
250
/** Disabled keys */
251
disabledKeys?: Iterable<Key>;
252
/** Sort descriptor */
253
sortDescriptor?: SortDescriptor;
254
/** Handler called when sort changes */
255
onSortChange?: (descriptor: SortDescriptor) => void;
256
/** Handler called when a row is activated */
257
onAction?: (key: Key) => void;
258
/** Handler called on row expansion */
259
onExpandedChange?: (keys: Set<Key>) => void;
260
/** Whether rows can be resized */
261
allowsResizing?: boolean;
262
/** Whether column headers are sticky */
263
stickyColumnHeaders?: boolean;
264
}
265
266
interface GridAria {
267
/** Props for the table grid element */
268
gridProps: DOMAttributes<Element>;
269
}
270
```
271
272
### Tree
273
274
Provides tree view behavior with hierarchical navigation and expansion.
275
276
```typescript { .api }
277
/**
278
* Provides tree behavior and accessibility
279
* @param props - Tree configuration
280
* @param state - Tree state
281
* @param ref - Ref to the tree element
282
* @returns Tree props and state
283
*/
284
function useTree<T>(props: AriaTreeProps<T>, state: TreeState<T>, ref: RefObject<Element>): TreeAria;
285
286
/**
287
* Provides tree item behavior with expansion and selection
288
* @param props - Tree item configuration
289
* @param state - Tree state
290
* @param ref - Ref to the tree item element
291
* @returns Tree item props and state
292
*/
293
function useTreeItem<T>(props: AriaTreeItemOptions<T>, state: TreeState<T>, ref: RefObject<Element>): TreeItemAria;
294
295
interface AriaTreeProps<T> extends TreeProps<T> {
296
/** Items in the tree */
297
items?: Iterable<T>;
298
/** Selection mode */
299
selectionMode?: SelectionMode;
300
/** Selected keys */
301
selectedKeys?: 'all' | Iterable<Key>;
302
/** Default selected keys (uncontrolled) */
303
defaultSelectedKeys?: 'all' | Iterable<Key>;
304
/** Handler called when selection changes */
305
onSelectionChange?: (keys: Selection) => void;
306
/** Expanded keys */
307
expandedKeys?: Iterable<Key>;
308
/** Default expanded keys (uncontrolled) */
309
defaultExpandedKeys?: Iterable<Key>;
310
/** Handler called when expansion changes */
311
onExpandedChange?: (keys: Set<Key>) => void;
312
/** Disabled keys */
313
disabledKeys?: Iterable<Key>;
314
/** Handler called when an item is activated */
315
onAction?: (key: Key) => void;
316
/** Whether the tree is disabled */
317
isDisabled?: boolean;
318
/** Auto-focus behavior */
319
autoFocus?: boolean | FocusStrategy;
320
/** Whether focus should wrap */
321
shouldFocusWrap?: boolean;
322
}
323
324
interface TreeAria {
325
/** Props for the tree element */
326
treeProps: DOMAttributes<Element>;
327
}
328
329
interface AriaTreeItemOptions<T> {
330
/** Key for the tree item */
331
key: Key;
332
/** Whether the item is disabled */
333
isDisabled?: boolean;
334
/** Whether the item should be focused */
335
shouldSelectOnPressUp?: boolean;
336
/** Whether the item should use virtual focus */
337
shouldUseVirtualFocus?: boolean;
338
/** Ref for the tree item */
339
ref?: RefObject<Element>;
340
}
341
342
interface TreeItemAria {
343
/** Props for the tree item element */
344
rowProps: DOMAttributes<Element>;
345
/** Props for the tree item content */
346
gridCellProps: DOMAttributes<Element>;
347
/** Props for the expand button */
348
buttonProps: ButtonHTMLAttributes<HTMLButtonElement>;
349
/** Props for the checkbox */
350
checkboxProps: InputHTMLAttributes<HTMLInputElement>;
351
/** Whether the item is selected */
352
isSelected: boolean;
353
/** Whether the item is expanded */
354
isExpanded: boolean;
355
/** Whether the item is disabled */
356
isDisabled: boolean;
357
/** Whether the item is pressed */
358
isPressed: boolean;
359
/** Level of the item in the tree */
360
level: number;
361
/** Whether the item has child items */
362
hasChildRows: boolean;
363
}
364
```
365
366
### Link
367
368
Provides link behavior with proper accessibility and routing integration.
369
370
```typescript { .api }
371
/**
372
* Provides link behavior and accessibility
373
* @param props - Link configuration
374
* @param ref - Ref to the link element
375
* @returns Link props and state
376
*/
377
function useLink(props: AriaLinkOptions, ref: RefObject<Element>): LinkAria;
378
379
interface AriaLinkOptions {
380
/** Whether the link is disabled */
381
isDisabled?: boolean;
382
/** Handler called when the link is activated */
383
onPress?: (e: PressEvent) => void;
384
/** Element type to render as */
385
elementType?: React.ElementType;
386
}
387
388
interface LinkAria {
389
/** Props for the link element */
390
linkProps: AnchorHTMLAttributes<HTMLAnchorElement>;
391
/** Whether the link is pressed */
392
isPressed: boolean;
393
}
394
```
395
396
### Tags
397
398
Provides tag group behavior for managing collections of tags or chips.
399
400
```typescript { .api }
401
/**
402
* Provides tag group behavior and accessibility
403
* @param props - Tag group configuration
404
* @param state - Tag group state
405
* @param ref - Ref to the tag group element
406
* @returns Tag group props and state
407
*/
408
function useTagGroup<T>(props: AriaTagGroupProps<T>, state: ListState<T>, ref: RefObject<Element>): TagGroupAria;
409
410
/**
411
* Provides individual tag behavior
412
* @param props - Tag configuration
413
* @param state - Tag group state
414
* @param ref - Ref to the tag element
415
* @returns Tag props and state
416
*/
417
function useTag<T>(props: AriaTagProps, state: ListState<T>, ref: RefObject<Element>): TagAria;
418
419
interface AriaTagGroupProps<T> {
420
/** Items in the tag group */
421
items?: Iterable<T>;
422
/** Selected keys */
423
selectedKeys?: 'all' | Iterable<Key>;
424
/** Default selected keys (uncontrolled) */
425
defaultSelectedKeys?: 'all' | Iterable<Key>;
426
/** Handler called when selection changes */
427
onSelectionChange?: (keys: Selection) => void;
428
/** Handler called when a tag is removed */
429
onRemove?: (keys: Set<Key>) => void;
430
/** Whether tags can be removed */
431
allowsRemoving?: boolean;
432
/** Whether the tag group is disabled */
433
isDisabled?: boolean;
434
/** Label for the tag group */
435
label?: ReactNode;
436
/** Description for the tag group */
437
description?: ReactNode;
438
/** Error message for the tag group */
439
errorMessage?: ReactNode;
440
}
441
442
interface TagGroupAria {
443
/** Props for the tag group element */
444
gridProps: DOMAttributes<Element>;
445
/** Props for the label element */
446
labelProps: DOMAttributes<Element>;
447
/** Props for the description element */
448
descriptionProps: DOMAttributes<Element>;
449
/** Props for the error message element */
450
errorMessageProps: DOMAttributes<Element>;
451
}
452
453
interface AriaTagProps {
454
/** Key for the tag */
455
key?: Key;
456
/** Whether the tag is disabled */
457
isDisabled?: boolean;
458
/** Text content of the tag */
459
textContent?: string;
460
/** Whether the tag can be removed */
461
allowsRemoving?: boolean;
462
}
463
464
interface TagAria {
465
/** Props for the tag row element */
466
rowProps: DOMAttributes<Element>;
467
/** Props for the tag content element */
468
gridCellProps: DOMAttributes<Element>;
469
/** Props for the remove button */
470
removeButtonProps: ButtonHTMLAttributes<HTMLButtonElement>;
471
/** Props for the tag description */
472
descriptionProps: DOMAttributes<Element>;
473
/** Whether the tag is selected */
474
isSelected: boolean;
475
/** Whether the tag is disabled */
476
isDisabled: boolean;
477
/** Whether the tag is pressed */
478
isPressed: boolean;
479
/** Whether the remove button is pressed */
480
isRemoveButtonPressed: boolean;
481
/** Allow removing the tag */
482
allowsRemoving: boolean;
483
}
484
```
485
486
### Separator
487
488
Provides separator element behavior for dividing content sections.
489
490
```typescript { .api }
491
/**
492
* Provides separator behavior and accessibility
493
* @param props - Separator configuration
494
* @param ref - Ref to the separator element
495
* @returns Separator props
496
*/
497
function useSeparator(props: SeparatorProps, ref: RefObject<Element>): SeparatorAria;
498
499
interface SeparatorProps {
500
/** Orientation of the separator */
501
orientation?: Orientation;
502
/** Element type to render */
503
elementType?: string;
504
}
505
506
interface SeparatorAria {
507
/** Props for the separator element */
508
separatorProps: DOMAttributes<Element>;
509
}
510
```
511
512
### Landmark
513
514
Provides landmark region behavior for page structure and navigation.
515
516
```typescript { .api }
517
/**
518
* Provides landmark behavior and accessibility
519
* @param props - Landmark configuration
520
* @param ref - Ref to the landmark element
521
* @returns Landmark props and controller
522
*/
523
function useLandmark(props: AriaLandmarkProps, ref: RefObject<Element>): LandmarkAria;
524
525
interface AriaLandmarkProps {
526
/** ARIA landmark role */
527
role?: AriaLandmarkRole;
528
/** Accessible name for the landmark */
529
'aria-label'?: string;
530
/** ID of element that labels the landmark */
531
'aria-labelledby'?: string;
532
}
533
534
interface LandmarkAria {
535
/** Props for the landmark element */
536
landmarkProps: DOMAttributes<Element>;
537
/** Landmark controller for managing focus */
538
landmarkController: LandmarkController;
539
}
540
541
type AriaLandmarkRole =
542
| 'banner'
543
| 'complementary'
544
| 'contentinfo'
545
| 'form'
546
| 'main'
547
| 'navigation'
548
| 'region'
549
| 'search';
550
551
interface LandmarkController {
552
/** Navigate to the next landmark */
553
nextLandmark(): void;
554
/** Navigate to the previous landmark */
555
previousLandmark(): void;
556
/** Get all landmarks on the page */
557
getLandmarks(): Element[];
558
}
559
```
560
561
## Types
562
563
```typescript { .api }
564
interface TabListState<T> {
565
/** Collection of tab items */
566
collection: Collection<Node<T>>;
567
/** Currently selected key */
568
selectedKey: Key | null;
569
/** Set the selected key */
570
setSelectedKey(key: Key): void;
571
/** Selected item */
572
selectedItem: Node<T> | null;
573
}
574
575
interface TableState<T> {
576
/** Collection of table items */
577
collection: Collection<Node<T>>;
578
/** Set of selected keys */
579
selectedKeys: Selection;
580
/** Set the selected keys */
581
setSelectedKeys(keys: Selection): void;
582
/** Sort descriptor */
583
sortDescriptor: SortDescriptor | null;
584
/** Set the sort descriptor */
585
setSortDescriptor(descriptor: SortDescriptor): void;
586
/** Set of expanded keys */
587
expandedKeys: Set<Key>;
588
/** Toggle expansion of a key */
589
toggleExpanded(key: Key): void;
590
}
591
592
interface TreeState<T> {
593
/** Collection of tree items */
594
collection: Collection<Node<T>>;
595
/** Set of selected keys */
596
selectedKeys: Selection;
597
/** Set the selected keys */
598
setSelectedKeys(keys: Selection): void;
599
/** Set of expanded keys */
600
expandedKeys: Set<Key>;
601
/** Toggle expansion of a key */
602
toggleExpanded(key: Key): void;
603
/** Currently focused key */
604
focusedKey: Key | null;
605
/** Set the focused key */
606
setFocusedKey(key: Key): void;
607
}
608
609
interface SortDescriptor {
610
/** Column key to sort by */
611
column: Key;
612
/** Sort direction */
613
direction: 'ascending' | 'descending';
614
}
615
```