0
# Focus Lock Components
1

2
Core React components for implementing focus trapping, including the main FocusLock component and helper components for specific focus behaviors like auto-focusing and free focus movement.
3

4
## Capabilities
5

6
### FocusLock Component
7

8
The main focus lock component that traps focus within its children, preventing tab navigation outside the component boundary.
9

10
```typescript { .api }
11
/**
12
 * Main focus lock component that traps focus within its children
13
 * @param props - Configuration options for focus behavior
14
 * @returns React component that wraps children with focus trapping
15
 */
16
declare const FocusLock: FC<ReactFocusLockProps>;
17

18
interface ReactFocusLockProps {
19
  /** Enable or disable the focus lock */
20
  disabled?: boolean;
21
  
22
  /** Return focus to previous position on unmount */
23
  returnFocus?: boolean | FocusOptions | ((returnTo: Element) => boolean | FocusOptions);
24
  
25
  /** 
26
   * @deprecated Can lead to wrong user experience. Use only if you know what you are doing.
27
   * Controls behavior of returning focus back to the lock
28
   */
29
  focusOptions?: FocusOptions;
30
  
31
  /** @deprecated Use persistentFocus=false instead */
32
  allowTextSelection?: boolean;
33
  
34
  /** Require persistent focus, disables text selection */
35
  persistentFocus?: boolean;
36
  
37
  /** Enable cross-iframe focus handling */
38
  crossFrame?: boolean;
39
  
40
  /** Auto-focus on activation */
41
  autoFocus?: boolean;
42
  
43
  /** Disable focus guards */
44
  noFocusGuards?: boolean | "tail";
45
  
46
  /** Handle positive tab indices */
47
  hasPositiveIndices?: boolean;
48
  
49
  /** Named group for scattered locks */
50
  group?: string;
51
  
52
  /** CSS class name */
53
  className?: string;
54
  
55
  /** Callback on lock activation */
56
  onActivation?(node: HTMLElement): void;
57
  
58
  /** Callback on lock deactivation */
59
  onDeactivation?(node: HTMLElement): void;
60
  
61
  /** Component element type, defaults to 'div' */
62
  as?: string | ElementType<LockProps & { children: ReactNode }>;
63
  
64
  /** Additional props for wrapper element */
65
  lockProps?: LockProps;
66
  
67
  /** React ref */
68
  ref?: Ref<HTMLElement>;
69
  
70
  /** Focus whitelist function */
71
  whiteList?: (activeElement: HTMLElement) => boolean;
72
  
73
  /** Scattered lock elements */
74
  shards?: Array<RefObject<any> | HTMLElement>;
75
  
76
  /** Child components */
77
  children?: ReactNode;
78
}
79
```
80

81
**Usage Examples:**
82

83
```typescript
84
import React from "react";
85
import FocusLock from "react-focus-lock";
86

87
// Basic focus lock
88
function BasicModal({ children, onClose }) {
89
  return (
90
    <FocusLock>
91
      <div className="modal">
92
        {children}
93
        <button onClick={onClose}>Close</button>
94
      </div>
95
    </FocusLock>
96
  );
97
}
98

99
// Advanced configuration
100
function AdvancedModal({ children, onClose }) {
101
  return (
102
    <FocusLock
103
      returnFocus={true}
104
      autoFocus={true}
105
      persistentFocus={false}
106
      onActivation={(node) => console.log("Focus lock activated", node)}
107
      onDeactivation={(node) => console.log("Focus lock deactivated", node)}
108
    >
109
      <div className="modal">
110
        {children}
111
        <button onClick={onClose}>Close</button>
112
      </div>
113
    </FocusLock>
114
  );
115
}
116

117
// Scattered focus with shards
118
function ScatteredModal({ children, headerRef, footerRef }) {
119
  return (
120
    <FocusLock shards={[headerRef, footerRef]}>
121
      <div className="modal-content">
122
        {children}
123
      </div>
124
    </FocusLock>
125
  );
126
}
127
```
128

129
### AutoFocusInside Component
130

131
Automatically focuses children on lock activation.
132

133
```typescript { .api }
134
/**
135
 * Automatically focuses children on lock activation
136
 * @param props - Component configuration
137
 * @returns React component that triggers autofocus
138
 */
139
declare class AutoFocusInside extends Component<AutoFocusProps> {}
140

141
interface AutoFocusProps {
142
  /** Child components */
143
  children: ReactNode;
144
  /** Disable autofocus behavior */
145
  disabled?: boolean;
146
  /** CSS class name */
147
  className?: string;
148
}
149
```
150

151
**Usage Example:**
152

153
```typescript
154
import { AutoFocusInside } from "react-focus-lock";
155

156
function FormModal() {
157
  return (
158
    <FocusLock>
159
      <div className="modal">
160
        <AutoFocusInside>
161
          <input placeholder="This will be auto-focused" />
162
        </AutoFocusInside>
163
        <button>Other button</button>
164
      </div>
165
    </FocusLock>
166
  );
167
}
168
```
169

170
### MoveFocusInside Component
171

172
Immediately moves focus inside children on mount.
173

174
```typescript { .api }
175
/**
176
 * Immediately moves focus inside children on mount
177
 * @param props - Component configuration
178
 * @returns React component that moves focus on mount
179
 */
180
declare class MoveFocusInside extends Component<AutoFocusProps> {}
181
```
182

183
**Usage Example:**
184

185
```typescript
186
import { MoveFocusInside } from "react-focus-lock";
187

188
function DialogWithForcedFocus() {
189
  return (
190
    <div className="dialog">
191
      <MoveFocusInside>
192
        <div>
193
          <input placeholder="Focus will move here immediately" />
194
          <button>Button</button>
195
        </div>
196
      </MoveFocusInside>
197
    </div>
198
  );
199
}
200
```
201

202
### FreeFocusInside Component
203

204
Allows free focus movement inside children, hiding them from FocusLock.
205

206
```typescript { .api }
207
/**
208
 * Allows free focus movement inside children, hiding from FocusLock
209
 * @param props - Component configuration
210
 * @returns React component that allows free focus
211
 */
212
declare class FreeFocusInside extends Component<FreeFocusProps> {}
213

214
interface FreeFocusProps {
215
  /** Child components */
216
  children: ReactNode;
217
  /** CSS class name */
218
  className?: string;
219
}
220
```
221

222
**Usage Example:**
223

224
```typescript
225
import FocusLock, { FreeFocusInside } from "react-focus-lock";
226

227
function ModalWithFreeArea() {
228
  return (
229
    <FocusLock>
230
      <div className="modal">
231
        <input placeholder="Locked input" />
232
        <FreeFocusInside>
233
          <div className="free-area">
234
            <input placeholder="Free focus input" />
235
            <button>Free focus button</button>
236
          </div>
237
        </FreeFocusInside>
238
        <button>Locked button</button>
239
      </div>
240
    </FocusLock>
241
  );
242
}
243
```
244

245
### InFocusGuard Component
246

247
Secures the focus around the node, providing invisible focus guards.
248

249
```typescript { .api }
250
/**
251
 * Secures the focus around the node with invisible guards
252
 * @param props - Component configuration
253
 * @returns React component that provides focus guards
254
 */
255
declare class InFocusGuard extends Component<InFocusGuardProps> {}
256

257
interface InFocusGuardProps {
258
  /** Child components */
259
  children?: ReactNode;
260
}
261
```
262

263
**Usage Example:**
264

265
```typescript
266
import { InFocusGuard } from "react-focus-lock";
267

268
function GuardedContent() {
269
  return (
270
    <InFocusGuard>
271
      <div>
272
        <input placeholder="Guarded input" />
273
        <button>Guarded button</button>
274
      </div>
275
    </InFocusGuard>
276
  );
277
}
278
```
279

280
### FocusLockUI Component
281

282
UI-only version of FocusLock that requires a separate sidecar for the focus trap logic.
283

284
```typescript { .api }
285
/**
286
 * UI-only version of FocusLock requiring external sidecar
287
 * @param props - Configuration including sidecar
288
 * @returns React component with UI logic only
289
 */
290
declare const FocusLockUI: FC<ReactFocusLockProps & { sideCar: FC<any> }>;
291
```
292

293
**Usage Example:**
294

295
```typescript
296
import { FocusLockUI } from "react-focus-lock/UI";
297
import sidecar from "react-focus-lock/sidecar";
298

299
function CustomFocusLock({ children }) {
300
  return (
301
    <FocusLockUI sideCar={sidecar}>
302
      {children}
303
    </FocusLockUI>
304
  );
305
}
306
```