onKeyStroke

Listen for keyboard keystrokes. By default, listens on keydown events on window.

Usage

import { onKeyStroke } from '@vueuse/core'

onKeyStroke('ArrowDown', (e) => {
  e.preventDefault()
})

See this table for all key codes.

Return Value

Returns a stop function to remove the event listener.

const stop = onKeyStroke('Escape', handler)

// Later, stop listening
stop()

Listen To Multiple Keys

import { onKeyStroke } from '@vueuse/core'

onKeyStroke(['s', 'S', 'ArrowDown'], (e) => {
  e.preventDefault()
})

// listen to all keys by passing `true` or skipping the key parameter
onKeyStroke(true, (e) => {
  e.preventDefault()
})
onKeyStroke((e) => {
  e.preventDefault()
})

Custom Key Predicate

You can pass a custom function to determine which keys should trigger the handler.

import { onKeyStroke } from '@vueuse/core'

onKeyStroke(
  e => e.key === 'A' && e.shiftKey,
  (e) => {
    console.log('Shift+A pressed')
  },
)

Custom Event Target

import { onKeyStroke } from '@vueuse/core'

onKeyStroke('A', (e) => {
  console.log('Key A pressed on document')
}, { target: document })

Ignore Repeated Events

The callback will trigger only once when pressing A and holding down. The dedupe option can also be a reactive ref.

import { onKeyStroke } from '@vueuse/core'

onKeyStroke('A', (e) => {
  console.log('Key A pressed')
}, { dedupe: true })

Reference: KeyboardEvent.repeat

Passive Mode

Set passive: true to use a passive event listener.

import { onKeyStroke } from '@vueuse/core'

onKeyStroke('A', handler, { passive: true })

Directive Usage

vue

<script setup lang="ts">
import { vOnKeyStroke } from '@vueuse/components'

function onUpdate(e: KeyboardEvent) {
  // impl...
}
</script>

<template>
  <input v-on-key-stroke:c,v="onUpdate" type="text">
  <!-- with options -->
  <input v-on-key-stroke:c,v="[onUpdate, { eventName: 'keyup' }]" type="text">
</template>

Custom Keyboard Event

import { onKeyStroke } from '@vueuse/core'
// ---cut---
onKeyStroke('Shift', (e) => {
  console.log('Shift key up')
}, { eventName: 'keyup' })

import { onKeyUp } from '@vueuse/core'
// ---cut---
onKeyUp('Shift', () => console.log('Shift key up'))

Shorthands

onKeyDown - alias for onKeyStroke(key, handler, {eventName: 'keydown'})
onKeyPressed - alias for onKeyStroke(key, handler, {eventName: 'keypress'})
onKeyUp - alias for onKeyStroke(key, handler, {eventName: 'keyup'})