0
# React Aria Focus
1

2
React Aria Focus provides accessible focus management hooks and components for React applications. It includes comprehensive focus containment, visual focus indicators, and programmatic focus navigation utilities designed to work seamlessly across different input modalities and assistive technologies.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import {
15
  FocusScope,
16
  FocusRing,
17
  useFocusManager,
18
  useFocusRing,
19
  useHasTabbableChild,
20
  createFocusManager,
21
  getFocusableTreeWalker,
22
  isElementInChildOfActiveScope,
23
  moveVirtualFocus,
24
  dispatchVirtualBlur,
25
  dispatchVirtualFocus,
26
  getVirtuallyFocusedElement,
27
  // Re-exported from other packages
28
  isFocusable,
29
  FocusableProvider,
30
  useFocusable,
31
  focusSafely
32
} from "@react-aria/focus";
33
```
34

35
For CommonJS:
36

37
```javascript
38
const {
39
  FocusScope,
40
  FocusRing,
41
  useFocusManager,
42
  useFocusRing,
43
  useHasTabbableChild,
44
  createFocusManager,
45
  getFocusableTreeWalker,
46
  isElementInChildOfActiveScope,
47
  moveVirtualFocus,
48
  dispatchVirtualBlur,
49
  dispatchVirtualFocus,
50
  getVirtuallyFocusedElement,
51
  // Re-exported from other packages
52
  isFocusable,
53
  FocusableProvider,
54
  useFocusable,
55
  focusSafely
56
} = require("@react-aria/focus");
57
```
58

59
## Basic Usage
60

61
```typescript
62
import React from "react";
63
import { FocusScope, FocusRing } from "@react-aria/focus";
64

65
function Dialog({ isOpen, onClose, children }) {
66
  if (!isOpen) return null;
67
  
68
  return (
69
    <div className="dialog-backdrop">
70
      <FocusScope contain restoreFocus autoFocus>
71
        <div className="dialog">
72
          <FocusRing focusRingClass="focus-visible">
73
            <button onClick={onClose}>Close</button>
74
          </FocusRing>
75
          {children}
76
        </div>
77
      </FocusScope>  
78
    </div>
79
  );
80
}
81

82
// Usage with focus manager
83
function CustomNavigableList() {
84
  const focusManager = useFocusManager();
85
  
86
  const handleKeyDown = (e: KeyboardEvent) => {
87
    switch (e.key) {
88
      case 'ArrowDown':
89
        focusManager?.focusNext();
90
        break;
91
      case 'ArrowUp':
92
        focusManager?.focusPrevious();
93
        break;
94
    }
95
  };
96
  
97
  return (
98
    <FocusScope>
99
      <div onKeyDown={handleKeyDown}>
100
        <button>Item 1</button>
101
        <button>Item 2</button>
102
        <button>Item 3</button>
103
      </div>
104
    </FocusScope>
105
  );
106
}
107
```
108

109
## Architecture
110

111
React Aria Focus is built around several key components:
112

113
- **Focus Containment**: `FocusScope` component provides focus trapping and restoration for modal dialogs and overlays
114
- **Visual Focus Indicators**: `FocusRing` component and `useFocusRing` hook provide keyboard-only focus rings that respect user input modality
115
- **Programmatic Navigation**: Focus managers enable keyboard navigation patterns like arrow key navigation in lists and grids  
116
- **Virtual Focus**: Utilities for managing aria-activedescendant patterns in complex widgets
117
- **Tree Walking**: Advanced focus tree traversal for finding focusable elements within scopes
118

119
## Capabilities
120

121
### Focus Scope Management
122

123
Focus containment system for modal dialogs, popover overlays, and other focus-trapped interfaces. Provides automatic focus restoration and keyboard navigation boundaries.
124

125
```typescript { .api }
126
interface FocusScopeProps {
127
  children: ReactNode;
128
  contain?: boolean;
129
  restoreFocus?: boolean;
130
  autoFocus?: boolean;
131
}
132

133
function FocusScope(props: FocusScopeProps): JSX.Element;
134

135
function useFocusManager(): FocusManager | undefined;
136
```
137

138
[Focus Scope Management](./focus-scope.md)
139

140
### Visual Focus Indicators
141

142
Keyboard-only focus rings that provide visual focus indicators only when users are navigating with keyboard, not mouse or touch.
143

144
```typescript { .api }
145
interface FocusRingProps {
146
  children: ReactElement;
147
  focusClass?: string;
148
  focusRingClass?: string;
149
  within?: boolean;
150
  isTextInput?: boolean;
151
  autoFocus?: boolean;
152
}
153

154
function FocusRing(props: FocusRingProps): ReactElement;
155

156
interface FocusRingAria {
157
  isFocused: boolean;
158
  isFocusVisible: boolean;
159
  focusProps: DOMAttributes;
160
}
161

162
function useFocusRing(props?: AriaFocusRingProps): FocusRingAria;
163
```
164

165
[Visual Focus Indicators](./focus-ring.md)
166

167
### Focus Navigation Utilities
168

169
Low-level utilities for creating custom focus managers, traversing focusable elements, and implementing keyboard navigation patterns.
170

171
```typescript { .api }
172
interface FocusManager {
173
  focusNext(opts?: FocusManagerOptions): FocusableElement | null;
174
  focusPrevious(opts?: FocusManagerOptions): FocusableElement | null;
175
  focusFirst(opts?: FocusManagerOptions): FocusableElement | null;
176
  focusLast(opts?: FocusManagerOptions): FocusableElement | null;
177
}
178

179
function createFocusManager(
180
  ref: RefObject<Element | null>,
181
  defaultOptions?: FocusManagerOptions
182
): FocusManager;
183

184
function getFocusableTreeWalker(
185
  root: Element,
186
  opts?: FocusManagerOptions,
187
  scope?: Element[]
188
): TreeWalker | ShadowTreeWalker;
189

190
function useHasTabbableChild(
191
  ref: RefObject<Element | null>,
192
  options?: AriaHasTabbableChildOptions
193
): boolean;
194

195
function isElementInChildOfActiveScope(element: Element): boolean;
196
```
197

198
[Focus Navigation Utilities](./focus-navigation.md)
199

200
### Virtual Focus System
201

202
Support for aria-activedescendant focus patterns commonly used in comboboxes, listboxes, and other composite widgets.
203

204
```typescript { .api }
205
function moveVirtualFocus(to: Element | null): void;
206
function dispatchVirtualBlur(from: Element, to: Element | null): void;
207
function dispatchVirtualFocus(to: Element, from: Element | null): void;
208
function getVirtuallyFocusedElement(document: Document): Element | null;
209
```
210

211
[Virtual Focus System](./virtual-focus.md)
212

213
### Re-exported Utilities
214

215
Backward-compatible utilities re-exported from other React Aria packages for convenience.
216

217
```typescript { .api }
218
// From @react-aria/utils
219
function isFocusable(element: Element): boolean;
220

221
// From @react-aria/interactions  
222
function FocusableProvider(props: FocusableProviderProps): ReactElement;
223
function useFocusable(props?: FocusableOptions): FocusableAria;
224
function focusSafely(element: FocusableElement): void;
225

226
type Focusable = FocusableElement;
227
```
228

229
These functions are re-exported for backward compatibility and convenience. For new code, consider importing them directly from their source packages.
230

231
## Core Types
232

233
```typescript { .api }
234
interface FocusManagerOptions {
235
  from?: Element;
236
  tabbable?: boolean;
237
  wrap?: boolean;
238
  accept?: (node: Element) => boolean;
239
}
240

241
interface AriaFocusRingProps {
242
  within?: boolean;
243
  isTextInput?: boolean;
244
  autoFocus?: boolean;
245
}
246

247
interface AriaHasTabbableChildOptions {
248
  isDisabled?: boolean;
249
}
250

251
// Re-exported types from @react-aria/interactions
252
interface FocusableAria {
253
  focusProps: DOMAttributes;
254
}
255

256
interface FocusableOptions {
257
  isDisabled?: boolean;
258
  onFocus?: (e: FocusEvent) => void;
259
  onBlur?: (e: FocusEvent) => void;
260
  onFocusChange?: (isFocused: boolean) => void;
261
}
262

263
interface FocusableProviderProps {
264
  children: ReactNode;
265
}
266

267
// Re-exported from @react-types/shared and React
268
type FocusableElement = Element;
269
type RefObject<T> = { current: T | null };
270
type ReactNode = React.ReactNode;
271
type ReactElement = React.ReactElement;
272
type DOMAttributes = React.DOMAttributes<Element>;
273
```