0
# React Focus Lock
1

2
React Focus Lock is a comprehensive focus management library that provides robust focus trapping functionality for React applications, primarily designed for modal dialogs, dropdown menus, and other UI components that require focus containment. The library implements accessibility-compliant focus management by automatically trapping keyboard focus within a designated area, preventing users from tabbing out of modal dialogs or other focused components while maintaining proper tab order.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import FocusLock from "react-focus-lock";
15
```
16

17
For accessing all components and hooks:
18

19
```typescript
20
import FocusLock, {
21
  AutoFocusInside,
22
  MoveFocusInside,
23
  FreeFocusInside,
24
  InFocusGuard,
25
  useFocusScope,
26
  useFocusController,
27
  useFocusState,
28
  useFocusInside
29
} from "react-focus-lock";
30
```
31

32
Alternative entry points:
33

34
```typescript
35
// UI components only (requires sidecar)
36
import { FocusLockUI } from "react-focus-lock/UI";
37

38
// Sidecar for custom integrations
39
import sidecar from "react-focus-lock/sidecar";
40
```
41

42
CommonJS:
43

44
```javascript
45
const FocusLock = require("react-focus-lock");
46
const { AutoFocusInside, useFocusScope } = require("react-focus-lock");
47
```
48

49
## Basic Usage
50

51
```typescript
52
import React, { useState } from "react";
53
import FocusLock from "react-focus-lock";
54

55
function ModalDialog({ isOpen, onClose, children }) {
56
  if (!isOpen) return null;
57

58
  return (
59
    <div className="overlay">
60
      <FocusLock returnFocus>
61
        <div className="modal">
62
          {children}
63
          <button onClick={onClose}>Close</button>
64
        </div>
65
      </FocusLock>
66
    </div>
67
  );
68
}
69

70
// Usage
71
function App() {
72
  const [showModal, setShowModal] = useState(false);
73

74
  return (
75
    <div>
76
      <button onClick={() => setShowModal(true)}>Open Modal</button>
77
      <ModalDialog isOpen={showModal} onClose={() => setShowModal(false)}>
78
        <h2>Modal Content</h2>
79
        <input placeholder="Focused input" />
80
        <button>Modal Button</button>
81
      </ModalDialog>
82
    </div>
83
  );
84
}
85
```
86

87
## Architecture
88

89
React Focus Lock is built around several key components:
90

91
- **Focus Lock Components**: Main `FocusLock` component and related helper components for controlling focus behavior
92
- **Focus Control Hooks**: React hooks for programmatic focus management and state tracking
93
- **Sidecar Architecture**: Split UI and logic for optimized bundle sizes
94
- **TypeScript Integration**: Full type safety with comprehensive interface definitions
95
- **Accessibility Compliance**: WAI-ARIA compliant focus management with cross-frame support
96

97
## Capabilities
98

99
### Focus Lock Components
100

101
Core React components for implementing focus trapping, including the main FocusLock component and helper components for specific focus behaviors.
102

103
```typescript { .api }
104
declare const FocusLock: FC<ReactFocusLockProps>;
105

106
interface ReactFocusLockProps {
107
  disabled?: boolean;
108
  returnFocus?: boolean | FocusOptions | ((returnTo: Element) => boolean | FocusOptions);
109
  autoFocus?: boolean;
110
  children?: ReactNode;
111
}
112
```
113

114
[Focus Lock Components](./focus-lock-components.md)
115

116
### Focus Control Hooks
117

118
React hooks for programmatic focus management, providing fine-grained control over focus behavior within and outside of focus locks.
119

120
```typescript { .api }
121
function useFocusScope(): FocusControl;
122
function useFocusController<Elements extends HTMLElement = HTMLElement>(
123
  ...shards: ReadonlyArray<HTMLElement | { current: HTMLElement | null }>
124
): FocusControl;
125

126
interface FocusControl {
127
  autoFocus(): Promise<void>;
128
  focusNext(options?: FocusOptions): Promise<void>;
129
  focusPrev(options?: FocusOptions): Promise<void>;
130
}
131
```
132

133
[Focus Control Hooks](./focus-control-hooks.md)
134

135
### TypeScript Types and Interfaces
136

137
Complete type definitions for all components, hooks, and configuration options, ensuring full type safety in TypeScript projects.
138

139
```typescript { .api }
140
interface FocusOptions {
141
  cycle?: boolean;
142
  onlyTabbable?: boolean;
143
}
144

145
interface FocusControl {
146
  autoFocus(): Promise<void>;
147
  focusNext(options?: FocusOptions): Promise<void>;
148
  focusPrev(options?: FocusOptions): Promise<void>;
149
  focusFirst(options?: Pick<FocusOptions, 'onlyTabbable'>): Promise<void>;
150
  focusLast(options?: Pick<FocusOptions, 'onlyTabbable'>): Promise<void>;
151
}
152
```
153

154
[TypeScript Types](./typescript-types.md)