0
# React Aria Utils
1

2
Essential utility functions and React hooks that serve as the foundational building blocks for React Aria's accessible UI component library. This package provides critical utilities for DOM manipulation, platform detection, React lifecycle management, accessibility features, and animation helpers.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { 
15
  useId, 
16
  mergeProps, 
17
  filterDOMProps, 
18
  focusWithoutScrolling,
19
  isMac,
20
  useEvent,
21
  useSyntheticLinkProps 
22
} from "@react-aria/utils";
23
```
24

25
For CommonJS:
26

27
```javascript
28
const { 
29
  useId, 
30
  mergeProps, 
31
  filterDOMProps, 
32
  focusWithoutScrolling,
33
  isMac,
34
  useEvent,
35
  useSyntheticLinkProps 
36
} = require("@react-aria/utils");
37
```
38

39
## Basic Usage
40

41
```typescript
42
import { useId, mergeProps, filterDOMProps, isMac } from "@react-aria/utils";
43

44
function MyComponent({ className, onClick, ...props }) {
45
  // Generate unique IDs for accessibility
46
  const labelId = useId();
47
  
48
  // Merge props intelligently
49
  const buttonProps = mergeProps(
50
    { 
51
      id: useId(),
52
      className: "button",
53
      onClick: (e) => console.log("default click")
54
    },
55
    { 
56
      className,
57
      onClick,
58
      "aria-labelledby": labelId
59
    }
60
  );
61
  
62
  // Filter props for DOM elements
63
  const domProps = filterDOMProps(props, { labelable: true });
64
  
65
  // Platform-specific behavior
66
  const shortcutKey = isMac() ? "⌘" : "Ctrl";
67
  
68
  return (
69
    <div>
70
      <label id={labelId}>My Button ({shortcutKey}+K)</label>
71
      <button {...buttonProps} {...domProps}>
72
        Click me
73
      </button>
74
    </div>
75
  );
76
}
77
```
78

79
## Architecture
80

81
React Aria Utils is organized around several key functional areas:
82

83
- **ID & Reference Management**: Unique ID generation and ref handling utilities for accessibility
84
- **Props & Event Utilities**: Intelligent prop merging, event chaining, and DOM prop filtering
85
- **Platform Detection**: Browser and device identification for conditional behavior
86
- **Focus & Accessibility**: Focus management, labeling, and accessibility utilities
87
- **Event Management**: Cross-platform event handling with automatic cleanup
88
- **Scrolling & Layout**: Viewport tracking, scroll utilities, and resize observation
89
- **Links & Navigation**: Client-side routing integration and synthetic link handling
90
- **Animation & Transitions**: Enter/exit animation management with CSS integration
91
- **State & Effects**: Custom hooks for React lifecycle and state management
92
- **Shadow DOM Support**: Complete shadow DOM traversal and manipulation utilities
93

94
## Capabilities
95

96
### ID & Reference Management
97

98
Core utilities for generating accessible IDs and managing React refs across components.
99

100
```typescript { .api }
101
function useId(defaultId?: string): string;
102
function mergeIds(idA: string, idB: string): string;
103
function useSlotId(depArray?: ReadonlyArray<any>): string;
104
function mergeRefs<T>(...refs: (Ref<T> | null | undefined)[]): Ref<T>;
105
function useObjectRef<T>(ref?: ForwardedRef<T>): MutableRefObject<T | null>;
106
```
107

108
[ID & Reference Management](./id-and-refs.md)
109

110
### Props & Event Utilities
111

112
Intelligent prop merging, event chaining, and DOM attribute filtering for React components.
113

114
```typescript { .api }
115
function mergeProps<T extends Props[]>(...args: T): UnionToIntersection<TupleTypes<T>>;
116
function chain(...callbacks: any[]): (...args: any[]) => void;
117
function filterDOMProps(props: DOMProps, opts?: FilterDOMPropsOptions): DOMAttributes;
118

119
interface FilterDOMPropsOptions {
120
  labelable?: boolean;
121
  isLink?: boolean;
122
  global?: boolean;
123
  events?: boolean;
124
  propNames?: Set<string>;
125
}
126
```
127

128
[Props & Event Utilities](./props-and-events.md)
129

130
### Platform Detection
131

132
Browser and device identification utilities for conditional behavior and platform-specific features.
133

134
```typescript { .api }
135
function isMac(): boolean;
136
function isIPhone(): boolean;
137
function isIPad(): boolean;
138
function isIOS(): boolean;
139
function isAppleDevice(): boolean;
140
function isWebKit(): boolean;
141
function isChrome(): boolean;
142
function isAndroid(): boolean;
143
function isFirefox(): boolean;
144
```
145

146
[Platform Detection](./platform-detection.md)
147

148
### Focus & Accessibility
149

150
Focus management, element accessibility checks, and ARIA labeling utilities.
151

152
```typescript { .api }
153
function focusWithoutScrolling(element: FocusableElement): void;
154
function isFocusable(element: Element): boolean;
155
function isTabbable(element: Element): boolean;
156
function useLabels(props: AriaLabelingProps, defaultLabel?: string): DOMProps & AriaLabelingProps;
157
function useDescription(description: string | undefined): DOMProps & AriaLabelingProps;
158

159
interface AriaLabelingProps {
160
  "aria-label"?: string;
161
  "aria-labelledby"?: string;
162
  "aria-describedby"?: string;
163
}
164
```
165

166
[Focus & Accessibility](./focus-and-accessibility.md)
167

168
### Event Management
169

170
Cross-platform event handling with automatic cleanup and stable function references.
171

172
```typescript { .api }
173
function useEvent<K extends keyof GlobalEventHandlersEventMap>(
174
  ref: RefObject<EventTarget | null>,
175
  event: K,
176
  handler?: (this: Document, ev: GlobalEventHandlersEventMap[K]) => any,
177
  options?: AddEventListenerOptions
178
): void;
179

180
interface GlobalListeners {
181
  addGlobalListener<K extends keyof DocumentEventMap>(
182
    el: EventTarget,
183
    type: K,
184
    listener: (this: Document, ev: DocumentEventMap[K]) => any,
185
    options?: AddEventListenerOptions | boolean
186
  ): void;
187
  removeGlobalListener<K extends keyof DocumentEventMap>(
188
    el: EventTarget,
189
    type: K,
190
    listener: (this: Document, ev: DocumentEventMap[K]) => any,
191
    options?: EventListenerOptions | boolean
192
  ): void;
193
  removeAllGlobalListeners(): void;
194
}
195

196
function useGlobalListeners(): GlobalListeners;
197
function useEffectEvent<T extends Function>(fn?: T): T;
198
```
199

200
[Event Management](./event-management.md)
201

202
### Scrolling & Layout
203

204
Viewport tracking, scroll utilities, element positioning, and resize observation.
205

206
```typescript { .api }
207
function getScrollParent(node: Element, checkForOverflow?: boolean): Element;
208
function getScrollParents(node: Element): Element[];
209
function isScrollable(element: Element, checkForOverflow?: boolean): boolean;
210
function scrollIntoView(scrollView: HTMLElement, element: HTMLElement): void;
211
function scrollIntoViewport(targetElement: Element, opts?: { containingElement?: Element }): void;
212

213
interface ViewportSize {
214
  width: number;
215
  height: number;
216
}
217

218
function useViewportSize(): ViewportSize;
219
function useResizeObserver<T extends Element>(options: {
220
  ref: RefObject<T>;
221
  box?: ResizeObserverBoxOptions;
222
  onResize: () => void;
223
}): void;
224
```
225

226
[Scrolling & Layout](./scrolling-and-layout.md)
227

228
### Links & Navigation
229

230
Client-side routing integration, synthetic link handling, and programmatic navigation.
231

232
```typescript { .api }
233
interface Router {
234
  isNative: boolean;
235
  open: (target: HTMLAnchorElement, modifiers: Modifiers, setOpening?: boolean) => void;
236
  useHref?: (href: string) => string;
237
}
238

239
function RouterProvider(props: { navigate: (path: string) => void; useHref?: (href: string) => string; children: ReactNode }): JSX.Element;
240
function useRouter(): Router;
241
function openLink(target: HTMLAnchorElement, modifiers: Modifiers, setOpening?: boolean): void;
242
function shouldClientNavigate(link: HTMLAnchorElement, modifiers: Modifiers): boolean;
243
function useSyntheticLinkProps(props: LinkDOMProps): DOMAttributes<HTMLElement>;
244
function useLinkProps(props?: LinkDOMProps): LinkDOMProps;
245

246
interface Modifiers {
247
  metaKey: boolean;
248
  ctrlKey: boolean;
249
  altKey: boolean;
250
  shiftKey: boolean;
251
}
252
```
253

254
[Links & Navigation](./links-and-navigation.md)
255

256
### Animation & Transitions
257

258
Enter/exit animation management with CSS integration and transition coordination.
259

260
```typescript { .api }
261
function useEnterAnimation(ref: RefObject<HTMLElement>, isReady?: boolean): boolean;
262
function useExitAnimation(ref: RefObject<HTMLElement>, isOpen: boolean): boolean;
263
function runAfterTransition(fn: () => void): void;
264
```
265

266
[Animation & Transitions](./animation-and-transitions.md)
267

268
### State & Effects
269

270
Custom React hooks for lifecycle management, state synchronization, and optimized effects.
271

272
```typescript { .api }
273
function useUpdateEffect(effect: EffectCallback, deps?: DependencyList): void;
274
function useUpdateLayoutEffect(effect: EffectCallback, deps?: DependencyList): void;
275
function useLayoutEffect: typeof React.useLayoutEffect;
276
function useValueEffect<T>(defaultValue: T): [T, (value: T | (() => Generator<T>)) => void];
277
function useDeepMemo<T>(value: T, isEqual?: (a: T, b: T) => boolean): T;
278
function useFormReset<T>(ref: RefObject<HTMLFormElement | HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>, initialValue: T, onReset: (value: T) => void): void;
279
```
280

281
[State & Effects](./state-and-effects.md)
282

283
### Virtual Events & Input
284

285
Detection and handling of virtual events from assistive technology and keyboard navigation.
286

287
```typescript { .api }
288
function isVirtualClick(event: MouseEvent | PointerEvent): boolean;
289
function isVirtualPointerEvent(event: PointerEvent): boolean;
290
function isCtrlKeyPressed(e: KeyboardEvent | MouseEvent | PointerEvent): boolean;
291
```
292

293
[Virtual Events & Input](./virtual-events-and-input.md)
294

295
### Shadow DOM Support
296

297
Complete shadow DOM traversal, manipulation, and compatibility utilities.
298

299
```typescript { .api }
300
class ShadowTreeWalker implements TreeWalker {
301
  // Full TreeWalker interface implementation
302
}
303

304
function createShadowTreeWalker(
305
  doc: Document,
306
  root: Node,
307
  whatToShow?: number,
308
  filter?: NodeFilter | null
309
): TreeWalker;
310

311
function getActiveElement(doc?: Document): Element | null;
312
function getEventTarget<T extends Event>(event: T): Element | null;
313
function nodeContains(node: Node, otherNode: Node): boolean;
314
```
315

316
[Shadow DOM Support](./shadow-dom-support.md)
317

318
### Load More & Infinite Scrolling
319

320
Utilities for implementing infinite scrolling, pagination, and load-more functionality.
321

322
```typescript { .api }
323
function useLoadMore(props: LoadMoreProps, ref: RefObject<HTMLElement | null>): void;
324

325
function useLoadMoreSentinel(
326
  props: LoadMoreSentinelProps,
327
  ref: RefObject<HTMLElement | null>
328
): void;
329

330
// Experimental alias
331
function UNSTABLE_useLoadMoreSentinel(
332
  props: LoadMoreSentinelProps,
333
  ref: RefObject<HTMLElement | null>
334
): void;
335

336
interface LoadMoreProps {
337
  isLoading?: boolean;
338
  onLoadMore?: () => void;
339
  scrollOffset?: number;
340
  items?: any;
341
}
342

343
interface LoadMoreSentinelProps extends Omit<AsyncLoadable, 'isLoading'> {
344
  collection: Collection<any>;
345
  onLoadMore?: () => void;
346
  scrollOffset?: number;
347
}
348
```
349

350
### Miscellaneous Utilities
351

352
Additional utilities for DOM helpers, value management, drag gestures, and utility functions.
353

354
```typescript { .api }
355
function getOffset(element: Element, reverse?: boolean, orientation?: "horizontal" | "vertical"): number;
356
function getOwnerDocument(el: Element): Document;
357
function getOwnerWindow(el: Element): Window;
358
function isShadowRoot(node: Node): node is ShadowRoot;
359
function inertValue<T>(value: T): T;
360

361
// Deprecated drag utility
362
function useDrag1D(props: object): HTMLAttributes<HTMLElement>;
363

364
// Constants
365
const CLEAR_FOCUS_EVENT = "react-aria-clear-focus";
366
const FOCUS_EVENT = "react-aria-focus";
367

368
// Re-exported from @react-stately/utils
369
function clamp(value: number, min: number, max: number): number;
370
function snapValueToStep(value: number, step: number, min?: number): number;
371
```
372

373
[Miscellaneous Utilities](./miscellaneous-utilities.md)
374

375
## Types
376

377
```typescript { .api }
378
interface DOMProps {
379
  id?: string;
380
}
381

382
interface AriaLabelingProps {
383
  "aria-label"?: string;
384
  "aria-labelledby"?: string;
385
  "aria-describedby"?: string;
386
}
387

388
interface LinkDOMProps extends DOMProps {
389
  href?: string;
390
  target?: string;
391
  rel?: string;
392
  download?: boolean | string;
393
  ping?: string;
394
  referrerPolicy?: string;
395
}
396

397
interface LoadMoreProps {
398
  isLoading?: boolean;
399
  onLoadMore?: () => void;
400
  scrollOffset?: number;
401
  items?: any;
402
}
403

404
interface AsyncLoadable {
405
  isLoading?: boolean;
406
  onLoadMore?: () => any;
407
}
408

409
interface LoadMoreSentinelProps extends Omit<AsyncLoadable, 'isLoading'> {
410
  collection: Collection<any>;
411
  onLoadMore?: () => void;
412
  scrollOffset?: number;
413
}
414

415
interface Collection<T> {
416
  // Collection interface from @react-types/shared - provides methods for managing collections of items
417
}
418

419
type FocusableElement = HTMLElement | SVGElement;
420

421
interface ViewportSize {
422
  width: number;
423
  height: number;
424
}
425
```