0
# React Aria
1

2
React Aria is a comprehensive library of unstyled React hooks that provides accessible UI primitives for building design systems and component libraries. It implements accessibility and behavior according to WAI-ARIA Authoring Practices, offering full screen reader and keyboard navigation support tested across multiple browsers, devices, and platforms.
3

4
## Package Information
5

6
- **Package Name**: react-aria
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install react-aria`
10

11
## Core Imports
12

13
```typescript
14
import { useButton, useTextField, useCheckbox } from "react-aria";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { useButton, useTextField, useCheckbox } = require("react-aria");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import React from "react";
27
import { useButton } from "react-aria";
28

29
function MyButton(props) {
30
  let ref = React.useRef();
31
  let { buttonProps } = useButton(props, ref);
32

33
  return (
34
    <button {...buttonProps} ref={ref}>
35
      {props.children}
36
    </button>
37
  );
38
}
39

40
// Usage
41
<MyButton onPress={() => alert('Button pressed!')}>
42
  Click me
43
</MyButton>
44
```
45

46
## Architecture
47

48
React Aria is built around several key design principles:
49

50
- **Unstyled Components**: Provides behavior and accessibility without any visual styling
51
- **Hook-Based API**: Uses React hooks following `use*` naming convention for all functionality
52
- **WAI-ARIA Compliance**: Implements ARIA authoring practices for full accessibility support
53
- **Platform Adaptive**: Handles mouse, touch, keyboard, and screen reader interactions appropriately
54
- **Type Safety**: Full TypeScript support with comprehensive type definitions
55
- **Internationalization**: Built-in support for 30+ languages with RTL layout and localized formatting
56
- **Meta-Package Structure**: Aggregates focused hooks from individual @react-aria/* packages
57

58
## Capabilities
59

60
### Form Controls
61

62
Interactive form elements with full accessibility support including labels, validation, keyboard navigation, color inputs, progress indicators, and sliders.
63

64
```typescript { .api }
65
function useButton(props: AriaButtonProps, ref: RefObject<Element>): ButtonAria;
66
function useToggleButton(props: AriaToggleButtonProps, ref: RefObject<Element>): ButtonAria;
67
function useToggleButtonGroup(props: AriaToggleButtonGroupProps, ref: RefObject<Element>): ToggleButtonGroupAria;
68
function useToggleButtonGroupItem(props: AriaToggleButtonGroupItemProps, state: ToggleButtonGroupState, ref: RefObject<Element>): ButtonAria;
69
function useTextField(props: AriaTextFieldProps, ref: RefObject<Element>): TextFieldAria;
70
function useNumberField(props: AriaNumberFieldProps, ref: RefObject<Element>): NumberFieldAria;
71
function useSearchField(props: AriaSearchFieldProps, ref: RefObject<Element>): SearchFieldAria;
72
function useCheckbox(props: AriaCheckboxProps, ref: RefObject<Element>): CheckboxAria;
73
function useCheckboxGroup(props: AriaCheckboxGroupProps, ref: RefObject<Element>): CheckboxGroupAria;
74
function useCheckboxGroupItem(props: AriaCheckboxGroupItemProps, state: CheckboxGroupState, ref: RefObject<Element>): CheckboxAria;
75
function useRadio(props: AriaRadioProps, ref: RefObject<Element>): RadioAria;
76
function useRadioGroup(props: AriaRadioGroupProps, ref: RefObject<Element>): RadioGroupAria;
77
function useSwitch(props: AriaSwitchProps, ref: RefObject<Element>): SwitchAria;
78
function useColorArea(props: AriaColorAreaProps, ref: RefObject<Element>): ColorAreaAria;
79
function useColorChannelField(props: AriaColorChannelFieldProps, ref: RefObject<Element>): ColorChannelFieldAria;
80
function useColorField(props: AriaColorFieldProps, ref: RefObject<Element>): ColorFieldAria;
81
function useColorSlider(props: AriaColorSliderProps, ref: RefObject<Element>): ColorSliderAria;
82
function useColorSwatch(props: AriaColorSwatchProps, ref: RefObject<Element>): ColorSwatchAria;
83
function useColorWheel(props: AriaColorWheelOptions, ref: RefObject<Element>): ColorWheelAria;
84
function useProgressBar(props: AriaProgressBarProps, ref: RefObject<Element>): ProgressBarAria;
85
function useMeter(props: AriaMeterProps, ref: RefObject<Element>): MeterAria;
86
function useSlider(props: AriaSliderProps, ref: RefObject<Element>): SliderAria;
87
function useSliderThumb(props: AriaSliderThumbProps, state: SliderState, ref: RefObject<Element>): SliderThumbAria;
88
function useField(props: AriaFieldProps, ref: RefObject<Element>): FieldAria;
89
function useLabel(props: LabelAriaProps, ref: RefObject<Element>): LabelAria;
90
```
91

92
[Form Controls](./form-controls.md)
93

94
### Selection Controls
95

96
Components for selecting from lists of options, including listboxes, comboboxes, and menus.
97

98
```typescript { .api }
99
function useListBox(props: AriaListBoxProps, state: ListState<T>, ref: RefObject<Element>): ListBoxAria;
100
function useComboBox(props: AriaComboBoxProps, state: ComboBoxState<T>, ref: RefObject<Element>): ComboBoxAria;
101
function useSelect(props: AriaSelectProps, state: SelectState<T>, ref: RefObject<Element>): SelectAria;
102
function useMenu(props: AriaMenuProps, state: TreeState<T>, ref: RefObject<Element>): MenuAria;
103
```
104

105
[Selection Controls](./selection-controls.md)
106

107
### Date and Time
108

109
Date and time input components with internationalization and accessibility support.
110

111
```typescript { .api }
112
function useDatePicker(props: AriaDatePickerProps, state: DatePickerState, ref: RefObject<Element>): DatePickerAria;
113
function useDateField(props: AriaDateFieldProps, state: DateFieldState, ref: RefObject<Element>): DateFieldAria;
114
function useCalendar(props: AriaCalendarProps, state: CalendarState, ref: RefObject<Element>): CalendarAria;
115
function useTimeField(props: AriaTimeFieldProps, state: TimeFieldState, ref: RefObject<Element>): TimeFieldAria;
116
```
117

118
[Date and Time](./date-time.md)
119

120
### Layout and Navigation
121

122
Components for organizing and navigating content including tabs, breadcrumbs, and tables.
123

124
```typescript { .api }
125
function useTabList(props: AriaTabListProps, state: TabListState<T>, ref: RefObject<Element>): TabListAria;
126
function useBreadcrumbs(props: AriaBreadcrumbsProps, ref: RefObject<Element>): BreadcrumbsAria;
127
function useTable(props: AriaTableProps, state: TableState<T>, ref: RefObject<Element>): GridAria;
128
function useTree(props: AriaTreeProps, state: TreeState<T>, ref: RefObject<Element>): TreeAria;
129
```
130

131
[Layout and Navigation](./layout-navigation.md)
132

133
### Overlays and Modals
134

135
Overlay components including dialogs, popovers, tooltips, and modals with proper focus management.
136

137
```typescript { .api }
138
function useDialog(props: AriaDialogProps, ref: RefObject<Element>): DialogAria;
139
function usePopover(props: AriaPopoverProps, state: PopoverState, ref: RefObject<Element>): PopoverAria;
140
function useTooltip(props: AriaTooltipProps, state: TooltipTriggerState): TooltipAria;
141
function useModal(options?: AriaModalOptions): ModalAria;
142
```
143

144
[Overlays and Modals](./overlays-modals.md)
145

146
### Interactions
147

148
Low-level interaction hooks for handling user input across different devices and interaction models.
149

150
```typescript { .api }
151
function usePress(props: PressHookProps): PressResult;
152
function useHover(props: HoverProps): HoverResult;
153
function useFocus(props: FocusProps): FocusResult;
154
function useKeyboard(props: KeyboardProps): KeyboardResult;
155
function useDrag(options: DragOptions): DragResult;
156
function useDrop(options: DropOptions): DropResult;
157
```
158

159
[Interactions](./interactions.md)
160

161
### Focus Management
162

163
Advanced focus management including focus rings, focus scopes, and focus restoration.
164

165
```typescript { .api }
166
function useFocusRing(props?: AriaFocusRingProps): FocusRingAria;
167
function useFocusManager(): FocusManager;
168
function useFocusable(props: FocusableOptions, domRef: RefObject<Element>): FocusableAria;
169
```
170

171
[Focus Management](./focus-management.md)
172

173
### Internationalization
174

175
Comprehensive i18n support with locale-aware formatting, RTL layout, and localization utilities.
176

177
```typescript { .api }
178
function useLocale(): { locale: string; direction: 'ltr' | 'rtl' };
179
function useDateFormatter(options: DateFormatterOptions): DateFormatter;
180
function useNumberFormatter(options: Intl.NumberFormatOptions): Intl.NumberFormat;
181
function useCollator(options: Intl.CollatorOptions): Intl.Collator;
182
```
183

184
[Internationalization](./internationalization.md)
185

186
### Toast Notifications
187

188
Toast notification system for displaying temporary messages and alerts.
189

190
```typescript { .api }
191
function useToast(props: AriaToastProps, state: ToastState, ref: RefObject<Element>): ToastAria;
192
function useToastRegion(props: AriaToastRegionProps, state: ToastRegionState, ref: RefObject<Element>): ToastRegionAria;
193
```
194

195
[Toast Notifications](./toast-notifications.md)
196

197
### Tags
198

199
Tag components for displaying and managing collections of labels or categories.
200

201
```typescript { .api }
202
function useTag(props: AriaTagProps, state: TagState, ref: RefObject<Element>): TagAria;
203
function useTagGroup(props: AriaTagGroupProps, state: TagGroupState, ref: RefObject<Element>): TagGroupAria;
204
```
205

206
[Tags](./tags.md)
207

208
### Drag and Drop
209

210
Comprehensive drag and drop system for building interactive interfaces with accessible keyboard navigation.
211

212
```typescript { .api }
213
function useDrag(options: DragOptions): DragResult;
214
function useDrop(options: DropOptions): DropResult;
215
function useDraggableCollection(props: DraggableCollectionProps): DraggableCollectionResult;
216
function useDroppableCollection(props: DroppableCollectionProps): DroppableCollectionResult;
217
function useDraggableItem(props: DraggableItemProps): DraggableItemResult;
218
function useDroppableItem(props: DroppableItemProps): DroppableItemResult;
219
function useDropIndicator(props: DropIndicatorProps): DropIndicatorResult;
220
function useClipboard(options: ClipboardOptions): ClipboardResult;
221
```
222

223
[Drag and Drop](./drag-drop.md)
224

225
### Disclosure
226

227
Disclosure components for expandable content sections.
228

229
```typescript { .api }
230
function useDisclosure(props: AriaDisclosureProps, ref: RefObject<Element>): DisclosureAria;
231
```
232

233
### Landmarks
234

235
Landmark components for improving page navigation and structure.
236

237
```typescript { .api }
238
function useLandmark(props: AriaLandmarkProps, ref: RefObject<Element>): LandmarkAria;
239
```
240

241
### Server-Side Rendering
242

243
SSR utilities for handling server-side rendering scenarios and hydration.
244

245
```typescript { .api }
246
function SSRProvider(props: SSRProviderProps): JSX.Element;
247
function useIsSSR(): boolean;
248
```
249

250
### Visually Hidden
251

252
Utilities for hiding content visually while keeping it accessible to screen readers.
253

254
```typescript { .api }
255
function VisuallyHidden(props: VisuallyHiddenProps): JSX.Element;
256
function useVisuallyHidden(props?: VisuallyHiddenOptions): VisuallyHiddenAria;
257
```
258

259
### Utilities
260

261
Utility hooks and functions for common React Aria patterns and prop management.
262

263
```typescript { .api }
264
function mergeProps(...props: any[]): any;
265
function chain(...callbacks: any[]): (...args: any[]) => void;
266
function useId(defaultId?: string): string;
267
function useObjectRef<T>(forwardedRef: ForwardedRef<T>): RefObject<T>;
268
function RouterProvider(props: RouterProviderProps): JSX.Element;
269
```
270

271
[Utilities](./utilities.md)
272

273
## Common Types
274

275
```typescript { .api }
276
type Key = string | number;
277

278
type Orientation = 'horizontal' | 'vertical';
279

280
type SelectionMode = 'none' | 'single' | 'multiple';
281

282
type ValidationState = 'valid' | 'invalid';
283

284
type NecessityIndicator = 'icon' | 'label';
285

286
interface PressEvent {
287
  type: 'pressstart' | 'pressend' | 'pressup' | 'press';
288
  pointerType: 'mouse' | 'pen' | 'touch' | 'keyboard' | 'virtual';
289
  target: Element;
290
  shiftKey: boolean;
291
  ctrlKey: boolean;
292
  metaKey: boolean;
293
  altKey: boolean;
294
}
295

296
interface HoverEvent {
297
  type: 'hoverstart' | 'hoverend';
298
  pointerType: 'mouse' | 'pen';
299
  target: Element;
300
}
301

302
interface FocusEvent {
303
  type: 'focus' | 'blur';
304
  target: Element;
305
  relatedTarget: Element | null;
306
}
307

308
interface KeyboardEvent {
309
  type: 'keydown' | 'keyup';
310
  key: string;
311
  code: string;
312
  shiftKey: boolean;
313
  ctrlKey: boolean;
314
  metaKey: boolean;
315
  altKey: boolean;
316
}
317

318
interface DOMAttributes<T = Element> {
319
  [key: string]: any;
320
}
321

322
interface RefObject<T> {
323
  current: T | null;
324
}
325

326
type ForwardedRef<T> = ((instance: T | null) => void) | MutableRefObject<T | null> | null;
327

328
interface MutableRefObject<T> {
329
  current: T;
330
}
331

332
interface Collection<T> {
333
  getKeys(): Iterable<Key>;
334
  getItem(key: Key): T | null;
335
  getSize(): number;
336
}
337

338
interface SelectionManager {
339
  selectedKeys: Set<Key>;
340
  isSelected(key: Key): boolean;
341
  select(key: Key): void;
342
  selectAll(): void;
343
  clearSelection(): void;
344
}
345
```