useMagicKeys | VueUse

useMagicKeys
​
Category
Sensors
Export Size
1.02 kB
Last Changed
2 months ago

Reactive keys pressed state, with magical keys combination support.

This function uses Proxy

It is NOT supported by IE 11 or below.

Demo
​

source

Press the following keys to test out
V
u
e
U
s
e
Shift
Vue
Use
Keys Pressed
Usage
​
js
import { useMagicKeys } from '@vueuse/core'

const { shift, space, a /* keys you want to monitor */ } = useMagicKeys()

watch(space, (v) => {
  if (v)
    console.log('space has been pressed')
})

watchEffect(() => {
  if (shift.value && a.value)
    console.log('Shift + A have been pressed')
})

Check out all the possible keycodes.

Combinations
​

You can magically use combinations (shortcuts/hotkeys) by connecting keys with + or _.

ts
import { useMagicKeys } from '@vueuse/core'

const keys = useMagicKeys()
const shiftCtrlA = keys['Shift+Ctrl+A']

watch(shiftCtrlA, (v) => {
  if (v)
    console.log('Shift + Ctrl + A have been pressed')
})
ts
import { useMagicKeys } from '@vueuse/core'

const { Ctrl_A_B, space, alt_s /* ... */ } = useMagicKeys()

watch(Ctrl_A_B, (v) => {
  if (v)
    console.log('Control+A+B have been pressed')
})

You can also use whenever function to make it shorter

ts
import { useMagicKeys, whenever } from '@vueuse/core'

const keys = useMagicKeys()

whenever(keys.shift_space, () => {
  console.log('Shift+Space have been pressed')
})
Current Pressed keys
​

A special property current is provided to representing all the keys been pressed currently.

ts
import { useMagicKeys } from '@vueuse/core'

const { current } = useMagicKeys()

console.log(current) // Set { 'control', 'a' }

whenever(
  () => current.has('a') && !current.has('b'),
  () => console.log('A is pressed but not B'),
)
Key Aliasing
​
ts
import { useMagicKeys, whenever } from '@vueuse/core'

const { shift_cool } = useMagicKeys({
  aliasMap: {
    cool: 'space',
  },
})

whenever(shift_cool, () => console.log('Shift + Space have been pressed'))

By default, we have some preconfigured alias for common practices.

Conditionally Disable
​

You 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.

ts
import { useActiveElement, useMagicKeys, whenever } from '@vueuse/core'
import { logicAnd } from '@vueuse/math'

const activeElement = useActiveElement()
const notUsingInput = computed(() =>
  activeElement.value?.tagName !== 'INPUT'
  && activeElement.value?.tagName !== 'TEXTAREA',)

const { tab } = useMagicKeys()

whenever(logicAnd(tab, notUsingInput), () => {
  console.log('Tab has been pressed outside of inputs!')
})
Custom Event Handler
​
ts
import { useMagicKeys, whenever } from '@vueuse/core'

const { ctrl_s } = useMagicKeys({
  passive: false,
  onEventFired(e) {
    if (e.ctrlKey && e.key === 's' && e.type === 'keydown')
      e.preventDefault()
  },
})

whenever(ctrl_s, () => console.log('Ctrl+S have been pressed'))

⚠️ This usage is NOT recommended, please use with caution.

Reactive Mode
​

By 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.

ts
const keys = useMagicKeys({ reactive: true })
html
<template>
  <div v-if="keys.shift">
    You are holding the Shift key!
  </div>
</template>
Source
​

Source • Demo • Docs

Contributors
​
Anthony Fu
Thiago Silveira
丶远方
Hartmut
Jelf
matrixbirds
lavolpecheprogramma
Kasper Seweryn
Thomas Gerbet
zzw
webfansplz
Ciro Lo Sapio
Alex Kozack
Changelog
​
v10.0.0-beta.4 on 4/13/2023
4d757 - feat(types)!: rename MaybeComputedRef to MaybeRefOrGetter
v9.7.0 on 12/16/2022
21d24 - fix: also clear 'current' on @focus|@blur (#2515)
v8.9.3 on 7/14/2022
6cefd - fix!: rename type MagicKeys to UseMagicKeysReturn (#1873)
v8.9.2 on 7/12/2022
9a718 - fix: fix setting properties of undefined value (#1856)
v8.9.1 on 7/8/2022
3c85d - fix: only clean up used keys, close #1793
a9ccc - feat(all): use MaybeComputedRef (#1768)
v8.9.0 on 7/6/2022
82510 - fix: reset refs on target blur (#1755)
5e76f - fix!: store key instead of keyCode in current (#1506)
v8.7.0 on 6/16/2022
d79e0 - fix: getModifierState is not function error in Chrome (#1654)