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
```