0
# TypeScript Types and Interfaces
1

2
Complete type definitions for all components, hooks, and configuration options, ensuring full type safety in TypeScript projects. These types provide comprehensive coverage of all React Focus Lock functionality.
3

4
## Core Interfaces
5

6
### ReactFocusLockProps Interface
7

8
Main configuration interface for the FocusLock component.
9

10
```typescript { .api }
11
interface ReactFocusLockProps<ChildrenType = ReactNode, LockProps = Record<string, any>> {
12
  /** Enable or disable the focus lock */
13
  disabled?: boolean;
14

15
  /** 
16
   * Return focus to previous position on unmount
17
   * Can be boolean, FocusOptions, or function for custom control
18
   */
19
  returnFocus?: boolean | FocusOptions | ((returnTo: Element) => boolean | FocusOptions);
20

21
  /** 
22
   * @deprecated Can lead to wrong user experience. Use only if you know what you are doing.
23
   * Controls behavior of returning focus back to the lock
24
   */
25
  focusOptions?: FocusOptions;
26

27
  /** 
28
   * @deprecated Use persistentFocus=false instead
29
   * Enable text selection, allows no focus
30
   */
31
  allowTextSelection?: boolean;
32

33
  /** 
34
   * Require persistent focus, disables text selection
35
   * @default false
36
   */
37
  persistentFocus?: boolean;
38

39
  /** 
40
   * Enable cross-iframe focus handling
41
   * @default true
42
   */
43
  crossFrame?: boolean;
44

45
  /** 
46
   * Auto-focus on activation
47
   * @default true
48
   */
49
  autoFocus?: boolean;
50

51
  /** Disable focus guards */
52
  noFocusGuards?: boolean | "tail";
53

54
  /** 
55
   * Handle positive tab indices
56
   * @default false
57
   */
58
  hasPositiveIndices?: boolean;
59

60
  /** Named group for scattered locks */
61
  group?: string;
62

63
  /** CSS class name */
64
  className?: string;
65

66
  /** Lifecycle callback on lock activation */
67
  onActivation?(node: HTMLElement): void;
68

69
  /** Lifecycle callback on lock deactivation */
70
  onDeactivation?(node: HTMLElement): void;
71

72
  /** Component element type, defaults to 'div' */
73
  as?: string | ElementType<LockProps & { children: ChildrenType }>;
74

75
  /** Additional props for wrapper element */
76
  lockProps?: LockProps;
77

78
  /** React ref */
79
  ref?: Ref<HTMLElement>;
80

81
  /** Focus whitelist function */
82
  whiteList?: (activeElement: HTMLElement) => boolean;
83

84
  /** Scattered lock elements */
85
  shards?: Array<RefObject<any> | HTMLElement>;
86

87
  /** Child components */
88
  children?: ChildrenType;
89
}
90
```
91

92
### FocusControl Interface
93

94
Interface for programmatic focus control operations.
95

96
```typescript { .api }
97
interface FocusControl {
98
  /** 
99
   * Move focus to the current scope, acts as autofocus
100
   * @returns Promise that resolves when focus is moved
101
   */
102
  autoFocus(): Promise<void>;
103

104
  /** 
105
   * Focus the next element in the scope
106
   * If active element is not in scope, autofocus will be triggered first
107
   * @param options - Focus behavior options
108
   * @returns Promise that resolves when focus is moved
109
   */
110
  focusNext(options?: FocusOptions): Promise<void>;
111

112
  /** 
113
   * Focus the previous element in the scope
114
   * If active element is not in scope, autofocus will be triggered first
115
   * @param options - Focus behavior options
116
   * @returns Promise that resolves when focus is moved
117
   */
118
  focusPrev(options?: FocusOptions): Promise<void>;
119

120
  /** 
121
   * Focus the first element in the scope
122
   * @param options - Focus behavior options
123
   * @returns Promise that resolves when focus is moved
124
   */
125
  focusFirst(options?: Pick<FocusOptions, 'onlyTabbable'>): Promise<void>;
126

127
  /** 
128
   * Focus the last element in the scope
129
   * @param options - Focus behavior options
130
   * @returns Promise that resolves when focus is moved
131
   */
132
  focusLast(options?: Pick<FocusOptions, 'onlyTabbable'>): Promise<void>;
133
}
134
```
135

136
### FocusOptions Type
137

138
Configuration options for focus behavior.
139

140
```typescript { .api }
141
interface FocusOptions {
142
  /** 
143
   * Enable focus cycle behavior
144
   * @default true
145
   */
146
  cycle?: boolean;
147

148
  /** 
149
   * Limit focusables to tabbable elements only (tabindex >= 0)
150
   * @default true
151
   */
152
  onlyTabbable?: boolean;
153
}
154
```
155

156
### FocusCallbacks Interface
157

158
Callback functions for focus state changes.
159

160
```typescript { .api }
161
interface FocusCallbacks {
162
  /** Called when focus enters the tracked element */
163
  onFocus(): void;
164

165
  /** Called when focus leaves the tracked element */
166
  onBlur(): void;
167
}
168
```
169

170
## Component Props Interfaces
171

172
### AutoFocusProps Interface
173

174
Props for AutoFocusInside and MoveFocusInside components.
175

176
```typescript { .api }
177
interface AutoFocusProps {
178
  /** Child components */
179
  children: ReactNode;
180

181
  /** Disable the autofocus behavior */
182
  disabled?: boolean;
183

184
  /** CSS class name */
185
  className?: string;
186
}
187
```
188

189
### FreeFocusProps Interface
190

191
Props for FreeFocusInside component.
192

193
```typescript { .api }
194
interface FreeFocusProps {
195
  /** Child components */
196
  children: ReactNode;
197

198
  /** CSS class name */
199
  className?: string;
200
}
201
```
202

203
### InFocusGuardProps Interface
204

205
Props for InFocusGuard component.
206

207
```typescript { .api }
208
interface InFocusGuardProps {
209
  /** Child components */
210
  children?: ReactNode;
211
}
212
```
213

214
## Hook Return Types
215

216
### useFocusState Return Type
217

218
Return type for the useFocusState hook.
219

220
```typescript { .api }
221
interface UseFocusStateReturn<T extends Element> {
222
  /** 
223
   * Whether currently focused or focus is inside
224
   * Updates when focus enters or leaves the element
225
   */
226
  active: boolean;
227

228
  /** 
229
   * Focus state string indicating type of focus relationship
230
   * Indicates the type of focus relationship
231
   */
232
  state: string;
233

234
  /** 
235
   * Focus event handler to be passed to the tracked element
236
   * Required for proper focus state tracking
237
   */
238
  onFocus: FocusEventHandler<T>;
239

240
  /** 
241
   * React ref to the tracked element
242
   * Used internally to monitor focus state
243
   */
244
  ref: RefObject<T>;
245
}
246
```
247

248
## Generic Type Parameters
249

250
### Elements Type Constraint
251

252
Generic type constraint for useFocusController hook.
253

254
```typescript { .api }
255
/**
256
 * Generic type constraint for HTML elements in focus controller
257
 * Extends HTMLElement to ensure proper element handling
258
 */
259
type Elements = HTMLElement;
260
```
261

262
### ChildrenType Generic
263

264
Generic type for children in ReactFocusLockProps.
265

266
```typescript { .api }
267
/**
268
 * Generic type for children prop in focus lock components
269
 * Defaults to ReactNode for maximum flexibility
270
 */
271
type ChildrenType = ReactNode;
272
```
273

274
### LockProps Generic
275

276
Generic type for additional lock properties.
277

278
```typescript { .api }
279
/**
280
 * Generic type for additional properties passed to lock wrapper
281
 * Defaults to Record<string, any> for flexibility
282
 */
283
type LockProps = Record<string, any>;
284
```
285

286
## Usage Examples
287

288
**Type-safe component usage:**
289

290
```typescript
291
import React, { useRef } from "react";
292
import FocusLock, { 
293
  ReactFocusLockProps, 
294
  FocusControl, 
295
  useFocusScope 
296
} from "react-focus-lock";
297

298
// Type-safe props
299
const focusLockProps: ReactFocusLockProps = {
300
  disabled: false,
301
  returnFocus: true,
302
  autoFocus: true,
303
  onActivation: (node: HTMLElement) => {
304
    console.log("Activated:", node);
305
  }
306
};
307

308
// Type-safe hook usage
309
function TypedModal() {
310
  const focusControl: FocusControl = useFocusScope();
311
  
312
  const handleNext = async (): Promise<void> => {
313
    await focusControl.focusNext({ cycle: true, onlyTabbable: false });
314
  };
315

316
  return (
317
    <div>
318
      <input />
319
      <button onClick={handleNext}>Next</button>
320
    </div>
321
  );
322
}
323

324
// Full example with types
325
function App() {
326
  return (
327
    <FocusLock {...focusLockProps}>
328
      <TypedModal />
329
    </FocusLock>
330
  );
331
}
332
```