1---
2category: Sensors
3---
4 
5# useMagicKeys
6 
7Reactive keys pressed state, with magical keys combination support.
8 
9## Usage
10 
11```ts
12import { useMagicKeys } from '@vueuse/core'
13 
14const { shift, space, a /* keys you want to monitor */ } = useMagicKeys()
15 
16watch(space, (v) => {
17  if (v)
18    console.log('space has been pressed')
19})
20 
21watchEffect(() => {
22  if (shift.value && a.value)
23    console.log('Shift + A have been pressed')
24})
25```
26 
27::: tip NOTE
28If you're using TypeScript with `noUncheckedIndexedAccess` enabled in your `tsconfig.json` (or using Nuxt which enables it by default), the destructured keys will have the type `ComputedRef<boolean> | undefined`.
29 
30The `noUncheckedIndexedAccess` TypeScript option adds `undefined` to any un-declared field accessed via index signatures. Since `useMagicKeys()` uses an index signature to allow accessing any key dynamically, TypeScript will treat destructured properties as potentially undefined for type safety.
31 
32You'll need to use optional chaining or wrap with a getter function:
33 
34```ts
35const { shift, space, a } = useMagicKeys()
36 
37watch(
38  () => space?.value,
39  (v) => {
40    if (v)
41      console.log('space has been pressed')
42  },
43)
44 
45watchEffect(() => {
46  if (shift?.value && a?.value)
47    console.log('Shift + A have been pressed')
48})
49```
50 
51Check the [TypeScript documentation](https://www.typescriptlang.org/tsconfig/#noUncheckedIndexedAccess) for more details about `noUncheckedIndexedAccess`.
52 
53:::
54 
55Check out [all the possible keycodes](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code/code_values).
56 
57### Combinations
58 
59You can magically use combinations (shortcuts/hotkeys) by connecting keys with `+` or `_`.
60 
61```ts
62import { useMagicKeys } from '@vueuse/core'
63 
64const keys = useMagicKeys()
65const shiftCtrlA = keys['Shift+Ctrl+A']
66 
67watch(shiftCtrlA, (v) => {
68  if (v)
69    console.log('Shift + Ctrl + A have been pressed')
70})
71```
72 
73```ts
74import { useMagicKeys } from '@vueuse/core'
75 
76const { Ctrl_A_B, space, alt_s /* ... */ } = useMagicKeys()
77 
78watch(Ctrl_A_B, (v) => {
79  if (v)
80    console.log('Control+A+B have been pressed')
81})
82```
83 
84You can also use `whenever` function to make it shorter
85 
86```ts
87import { useMagicKeys, whenever } from '@vueuse/core'
88 
89const keys = useMagicKeys()
90 
91whenever(keys.shift_space, () => {
92  console.log('Shift+Space have been pressed')
93})
94```
95 
96### Current Pressed keys
97 
98A special property `current` is provided to representing all the keys been pressed currently.
99 
100```ts
101import { useMagicKeys, whenever } from '@vueuse/core'
102 
103const { current } = useMagicKeys()
104 
105console.log(current) // Set { 'control', 'a' }
106 
107whenever(
108  () => current.has('a') && !current.has('b'),
109  () => console.log('A is pressed but not B'),
110)
111```
112 
113### Key Aliasing
114 
115```ts
116import { useMagicKeys, whenever } from '@vueuse/core'
117 
118const { shift_cool } = useMagicKeys({
119  aliasMap: {
120    cool: 'space',
121  },
122})
123 
124whenever(shift_cool, () => console.log('Shift + Space have been pressed'))
125```
126 
127By default, we have some [preconfigured alias for common practices](https://github.com/vueuse/vueuse/blob/main/packages/core/useMagicKeys/aliasMap.ts).
128 
129### Conditionally Disable
130 
131You might have some `<input />` elements in your apps, and you don't want to trigger the magic keys handling when users focused on those inputs. There is an example of using `useActiveElement` and `logicAnd` to do that.
132 
133```ts
134import { useActiveElement, useMagicKeys, whenever } from '@vueuse/core'
135import { logicAnd } from '@vueuse/math'
136 
137const activeElement = useActiveElement()
138const notUsingInput = computed(() =>
139  activeElement.value?.tagName !== 'INPUT'
140  && activeElement.value?.tagName !== 'TEXTAREA',)
141 
142const { tab } = useMagicKeys()
143 
144whenever(logicAnd(tab, notUsingInput), () => {
145  console.log('Tab has been pressed outside of inputs!')
146})
147```
148 
149### Custom Event Handler
150 
151```ts
152import { useMagicKeys, whenever } from '@vueuse/core'
153 
154const { ctrl_s } = useMagicKeys({
155  passive: false,
156  onEventFired(e) {
157    if (e.ctrlKey && e.key === 's' && e.type === 'keydown')
158      e.preventDefault()
159  },
160})
161 
162whenever(ctrl_s, () => console.log('Ctrl+S have been pressed'))
163```
164 
165> ⚠️ This usage is NOT recommended, please use with caution.
166 
167### Reactive Mode
168 
169By default, the values of `useMagicKeys()` are `Ref<boolean>`. If you want to use the object in the template, you can set it to reactive mode.
170 
171```ts
172import { useMagicKeys } from '@vueuse/core'
173// ---cut---
174const keys = useMagicKeys({ reactive: true })
175```
176 
177```vue
178<template>
179  <div v-if="keys.shift">
180    You are holding the Shift key!
181  </div>
182</template>
183```
184 
185## Type Declarations
186 
187```ts
188export interface UseMagicKeysOptions<Reactive extends boolean> {
189  /**
190   * Returns a reactive object instead of an object of refs
191   *
192   * @default false
193   */
194  reactive?: Reactive
195  /**
196   * Target for listening events
197   *
198   * @default window
199   */
200  target?: MaybeRefOrGetter<EventTarget>
201  /**
202   * Alias map for keys, all the keys should be lowercase
203   * { target: keycode }
204   *
205   * @example { ctrl: "control" }
206   * @default <predefined-map>
207   */
208  aliasMap?: Record<string, string>
209  /**
210   * Register passive listener
211   *
212   * @default true
213   */
214  passive?: boolean
215  /**
216   * Custom event handler for keydown/keyup event.
217   * Useful when you want to apply custom logic.
218   *
219   * When using `e.preventDefault()`, you will need to pass `passive: false` to useMagicKeys().
220   */
221  onEventFired?: (e: KeyboardEvent) => void | boolean
222}
223export interface MagicKeysInternal {
224  /**
225   * A Set of currently pressed keys,
226   * Stores raw keyCodes.
227   *
228   * @see https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key
229   */
230  current: Set<string>
231}
232export type UseMagicKeysReturn<Reactive extends boolean> = Readonly<
233  Record<string, Reactive extends true ? boolean : ComputedRef<boolean>> &
234    MagicKeysInternal
235>
236/**
237 * Reactive keys pressed state, with magical keys combination support.
238 *
239 * @see https://vueuse.org/useMagicKeys
240 */
241export declare function useMagicKeys<T extends boolean = false>(
242  options?: UseMagicKeysOptions<T>,
243): UseMagicKeysReturn<T>
244export { DefaultMagicKeysAliasMap } from "./aliasMap"
245```
246