You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
All hotkey combinations must use valid `KeyBoardEvent``"key"` values. A full list can be found on [MDN](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values) and Wes Bos has created a great [interactive lookup](https://keycode.info/).
20
24
21
25
```jsx
22
26
// Single keys
23
-
useHotkeys('Escape', () => {
24
-
console.log('Some action');
27
+
useHotkeys("Escape", () => {
28
+
console.log("Some action");
25
29
});
26
30
27
-
useHotkeys('F7', () => {
28
-
console.log('Some action');
31
+
useHotkeys("F7", () => {
32
+
console.log("Some action");
29
33
});
30
34
31
35
// Modifier combinations
32
-
useHotkeys('Meta+Shift+z', () => {
33
-
console.log('Some action');
36
+
useHotkeys("Meta+Shift+z", () => {
37
+
console.log("Some action");
34
38
});
35
39
36
40
// Key sequences
37
-
useHotkeys('w s d', () => {
38
-
console.log('Some action');
41
+
useHotkeys("w s d", () => {
42
+
console.log("Some action");
39
43
});
40
44
41
45
useHotkeys('w " " d', () => {
42
46
// space key in sequence (`w ' ' d` also works)
43
-
console.log('Some action');
47
+
console.log("Some action");
44
48
});
45
49
46
50
// Multiple key combinations mapped to the same callback
47
-
useHotkeys(['Control+z', 'Meta+z'], () => {
48
-
console.log('Some action');
51
+
useHotkeys(["Control+z", "Meta+z"], () => {
52
+
console.log("Some action");
49
53
});
50
54
51
-
useHotkeys(['a', 'Meta+z', 'w s d'], () => {
52
-
console.log('Some action');
53
-
})
55
+
useHotkeys(["a", "Meta+z", "w s d"], () => {
56
+
console.log("Some action");
57
+
});
54
58
```
55
59
56
60
The following patterns are **not** supported:
57
61
58
62
```jsx
59
63
// Modifier keys in sequences
60
-
useHotkeys('Control i d', () => {
64
+
useHotkeys("Control i d", () => {
61
65
console.log("I won't run!");
62
66
});
63
67
64
68
// Modifier combinations in sequences
65
-
useHotkeys('Control+z i d', () => {
69
+
useHotkeys("Control+z i d", () => {
66
70
console.log("I won't run!");
67
71
});
68
72
```
69
73
70
-
You can pass `AddEventListenerOptions` if you need to listen for `keydown` events in the capturing phase:
74
+
If you find a use case where the API is too restrictive you can use the escape hatch to perform whatever custom logic you need:
71
75
72
76
```jsx
73
-
useHotkeys('Escape', () => {
74
-
console.log('Some action');
75
-
}, true);
77
+
useHotkeys("*", (event) => {
78
+
console.log("I will run on every keydown event");
76
79
77
-
useHotkeys('Escape', () => {
78
-
console.log('Some action');
79
-
}, { capture:true });
80
+
if (customKeyLogic(event)) {
81
+
console.log("some action");
82
+
}
83
+
});
80
84
```
81
85
82
-
If you find a use case where the API is too restrictive you can use the escape hatch to perform whatever custom logic you need:
86
+
## Options
87
+
88
+
### `enabled`
89
+
90
+
You can disable the hook by passing `enabled: false`. When disabled the hook will stop listening for `keydown` events:
83
91
84
92
```jsx
85
-
useHotkeys('*', event=> {
86
-
console.log("I will run on every keydown");
93
+
useHotkeys(
94
+
"Escape",
95
+
() => {
96
+
console.log("I won't run!");
97
+
},
98
+
{ enabled:false }
99
+
);
100
+
```
87
101
88
-
if (customKeyLogic(event)) {
89
-
console.log("some action");
102
+
### `enableOnContentEditable`
103
+
104
+
By default, the hook will ignore `keydown` events originating from elements with the `contenteditable` attribute, since this behaviour is normally what you want. If you want to override this behaviour you can pass `enableOnContentEditable: true`:
105
+
106
+
```jsx
107
+
useHotkeys(
108
+
"Escape",
109
+
() => {
110
+
console.log("Some action");
111
+
},
112
+
{ enableOnContentEditable:true }
113
+
);
114
+
```
115
+
116
+
### `ignoredElementWhitelist`
117
+
118
+
By default, the hook will ignore `keydown` events originating from `INPUT` and `TEXTAREA` elements, since this behaviour is normally what you want. If you want to override this behaviour you can use `ignoredElementWhitelist`:
119
+
120
+
```jsx
121
+
useHotkeys(
122
+
"Escape",
123
+
() => {
124
+
console.log("I will now run on input elements");
125
+
},
126
+
{ ignoredElementWhitelist: ["INPUT"] }
127
+
);
128
+
129
+
useHotkeys(
130
+
"Escape",
131
+
() => {
132
+
console.log("I will now run on input and textarea elements");
You can pass [`AddEventListenerOptions`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#parameters) if you need to listen for `keydown` events in the capturing phase:
0 commit comments