npm-react-aria

1
# React Aria
2

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

5
## Package Information
6

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

12
## Core Imports
13

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

18
For CommonJS:
19

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

24
## Basic Usage
25

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

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

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

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

47
## Architecture
48

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

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

59
## Capabilities
60

61
### Form Controls
62

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

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

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

95
### Selection Controls
96

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

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

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

108
### Date and Time
109

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

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

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

121
### Layout and Navigation
122

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

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

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

134
### Overlays and Modals
135

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

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

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

147
### Interactions
148

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

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

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

162
### Focus Management
163

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

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

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

174
### Internationalization
175

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

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

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

187
### Toast Notifications
188

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

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

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

198
### Tags
199

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

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

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

209
### Drag and Drop
210

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

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

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

226
### Disclosure
227

228
Disclosure components for expandable content sections.
229

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

234
### Landmarks
235

236
Landmark components for improving page navigation and structure.
237

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

242
### Server-Side Rendering
243

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

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

251
### Visually Hidden
252

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

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

260
### Utilities
261

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

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

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

274
## Common Types
275

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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