0
# React Hotkeys Hook
1

2
React Hotkeys Hook is a React hook library for handling keyboard shortcuts in components in a declarative way. It enables developers to easily bind keyboard combinations (like ctrl+k, meta+s) to callback functions within React components, supporting advanced features like scopes for grouping hotkeys, focus trapping to limit hotkeys to specific elements, configurable behavior for form elements and content-editable areas, flexible options for keyup/keydown event handling, and key sequence support for vi-style command patterns.
3

4
## Package Information
5

6
- **Package Name**: react-hotkeys-hook
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install react-hotkeys-hook`
10

11
## Core Imports
12

13
```typescript
14
import { useHotkeys, HotkeysProvider, useHotkeysContext, isHotkeyPressed, useRecordHotkeys } from "react-hotkeys-hook";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { useHotkeys, HotkeysProvider, useHotkeysContext, isHotkeyPressed, useRecordHotkeys } = require("react-hotkeys-hook");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { useState } from 'react';
27
import { useHotkeys } from 'react-hotkeys-hook';
28

29
export const ExampleComponent = () => {
30
  const [count, setCount] = useState(0);
31
  
32
  // Basic hotkey binding
33
  useHotkeys('ctrl+k', () => setCount(count + 1), [count]);
34
  
35
  // Multiple key combinations for cross-platform support
36
  useHotkeys(['ctrl+s', 'cmd+s'], () => console.log('Save'));
37
  
38
  // Key sequences (vi-style)
39
  useHotkeys('g>i', () => console.log('Go to inbox'));
40

41
  return (
42
    <p>
43
      Pressed {count} times. Try Ctrl+K, Ctrl/Cmd+S, or g>i
44
    </p>
45
  );
46
};
47
```
48

49
## Architecture
50

51
React Hotkeys Hook is built around several key components:
52

53
- **Main Hook (`useHotkeys`)**: Primary hook for binding keyboard shortcuts to callbacks with extensive configuration options
54
- **Scope Management**: `HotkeysProvider` component and `useHotkeysContext` hook for organizing hotkeys into groups and controlling their active state
55
- **Key Recording**: `useRecordHotkeys` hook for capturing keyboard input to discover key combinations
56
- **Real-time Key Checking**: `isHotkeyPressed` utility for checking if keys are currently pressed
57
- **Focus Trapping**: Optional ref-based system to limit hotkeys to specific elements
58
- **Event Lifecycle**: Support for both keydown and keyup events with configurable preventDefault behavior
59
- **Key Sequences**: Support for multi-key sequences like vi-style commands (e.g., 'g>i', 'ctrl+k>ctrl+c')
60

61
## Capabilities
62

63
### Main Hotkey Hook
64

65
Primary hook for binding keyboard shortcuts to callback functions with extensive customization options including scopes, focus trapping, form element handling, and event lifecycle control.
66

67
```typescript { .api }
68
function useHotkeys<T extends HTMLElement>(
69
  keys: Keys,
70
  callback: HotkeyCallback,
71
  options?: OptionsOrDependencyArray,
72
  dependencies?: OptionsOrDependencyArray
73
): React.RefObject<T>;
74

75
type Keys = string | readonly string[];
76
type HotkeyCallback = (keyboardEvent: KeyboardEvent, hotkeysEvent: HotkeysEvent) => void;
77
type OptionsOrDependencyArray = Options | DependencyList;
78
```
79

80
[Main Hook](./main-hook.md)
81

82
### Scope Management
83

84
Context-based system for organizing hotkeys into groups and controlling their active state across an application, enabling complex hotkey hierarchies and conditional activation.
85

86
```typescript { .api }
87
function HotkeysProvider({
88
  initiallyActiveScopes,
89
  children
90
}: {
91
  initiallyActiveScopes?: string[];
92
  children: ReactNode;
93
}): JSX.Element;
94

95
function useHotkeysContext(): HotkeysContextType;
96

97
interface HotkeysContextType {
98
  hotkeys: ReadonlyArray<Hotkey>;
99
  activeScopes: string[];
100
  toggleScope: (scope: string) => void;
101
  enableScope: (scope: string) => void;
102
  disableScope: (scope: string) => void;
103
}
104
```
105

106
[Scope Management](./scope-management.md)
107

108
### Key Recording
109

110
Hook for recording keyboard input to discover key combinations, useful for hotkey configuration interfaces and debugging.
111

112
```typescript { .api }
113
function useRecordHotkeys(useKey?: boolean): [
114
  Set<string>,
115
  {
116
    start: () => void;
117
    stop: () => void;
118
    resetKeys: () => void;
119
    isRecording: boolean;
120
  }
121
];
122
```
123

124
[Key Recording](./key-recording.md)
125

126
### Real-time Key Checking
127

128
Utility function for checking if specified keys are currently pressed, enabling conditional logic based on keyboard state.
129

130
```typescript { .api }
131
function isHotkeyPressed(key: string | readonly string[], delimiter?: string): boolean;
132
```
133

134
[Key Checking](./key-checking.md)
135

136
## Core Types
137

138
```typescript { .api }
139
import type { RefObject, DependencyList, ReactNode } from 'react';
140

141
type Keys = string | readonly string[];
142
type HotkeyCallback = (keyboardEvent: KeyboardEvent, hotkeysEvent: HotkeysEvent) => void;
143
type OptionsOrDependencyArray = Options | DependencyList;
144

145
interface Options {
146
  enabled?: Trigger;
147
  enableOnFormTags?: readonly FormTags[] | boolean;
148
  enableOnContentEditable?: boolean;
149
  ignoreEventWhen?: (e: KeyboardEvent) => boolean;
150
  splitKey?: string;
151
  delimiter?: string;
152
  scopes?: Scopes;
153
  keyup?: boolean;
154
  keydown?: boolean;
155
  preventDefault?: Trigger;
156
  description?: string;
157
  document?: Document;
158
  ignoreModifiers?: boolean;
159
  eventListenerOptions?: EventListenerOptions;
160
  useKey?: boolean;
161
  sequenceTimeoutMs?: number;
162
  sequenceSplitKey?: string;
163
}
164

165
interface Hotkey extends KeyboardModifiers {
166
  keys?: readonly string[];
167
  scopes?: Scopes;
168
  description?: string;
169
  isSequence?: boolean;
170
}
171

172
interface KeyboardModifiers {
173
  alt?: boolean;
174
  ctrl?: boolean;
175
  meta?: boolean;
176
  shift?: boolean;
177
  mod?: boolean;
178
  useKey?: boolean;
179
}
180

181
type Trigger = boolean | ((keyboardEvent: KeyboardEvent, hotkeysEvent: HotkeysEvent) => boolean);
182
type Scopes = string | readonly string[];
183
type FormTags = 'input' | 'textarea' | 'select' | 'INPUT' | 'TEXTAREA' | 'SELECT';
184
type HotkeysEvent = Hotkey;
185

186
type EventListenerOptions =
187
  | {
188
      capture?: boolean;
189
      once?: boolean;
190
      passive?: boolean;
191
      signal?: AbortSignal;
192
    }
193
  | boolean; // useCapture
194
```