onKeyStroke ​
Listen for keyboard keystrokes.
Demo ​
Use the arrow keys or w a s d keys to control the movement of the ball.
Repeated events are ignored on the key `d` or `->`.
Usage ​
js
import { onKeyStroke } from '@vueuse/core'
onKeyStroke('ArrowDown', (e) => {
e.preventDefault()
})
See this table for all key codes.
Listen To Multiple Keys ​
js
import { onKeyStroke } from '@vueuse/core'
onKeyStroke(['s', 'S', 'ArrowDown'], (e) => {
e.preventDefault()
})
// listen to all keys by [true / skip the keyDefine]
onKeyStroke(true, (e) => {
e.preventDefault()
})
onKeyStroke((e) => {
e.preventDefault()
})
Custom Event Target ​
js
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 hold down.
js
import { onKeyStroke } from '@vueuse/core'
// use `autoRepeat` option
onKeyStroke('A', (e) => {
console.log('Key A pressed')
}, { dedupe: true })
Reference: KeyboardEvent.repeat
Directive Usage ​
This function also provides a directive version via the
@vueuse/components
package. Learn more about the 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 ​
js
onKeyStroke('Shift', (e) => {
console.log('Shift key up')
}, { eventName: 'keyup' })
Or
js
onKeyUp('Shift', () => console.log('Shift key up'))
Shorthands ​
onKeyDown
- alias foronKeyStroke(key, handler, {eventName: 'keydown'})
onKeyPressed
- alias foronKeyStroke(key, handler, {eventName: 'keypress'})
onKeyUp
- alias foronKeyStroke(key, handler, {eventName: 'keyup'})
Type Declarations ​
Show Type Declarations
typescript
export type KeyPredicate = (event: KeyboardEvent) => boolean
export type KeyFilter = true | string | string[] | KeyPredicate
export type KeyStrokeEventName = "keydown" | "keypress" | "keyup"
export interface OnKeyStrokeOptions {
eventName?: KeyStrokeEventName
target?: MaybeRefOrGetter<EventTarget | null | undefined>
passive?: boolean
/**
* Set to `true` to ignore repeated events when the key is being held down.
*
* @default false
*/
dedupe?: MaybeRefOrGetter<boolean>
}
/**
* Listen for keyboard keystrokes.
*
* @see https://vueuse.org/onKeyStroke
*/
export declare function onKeyStroke(
key: KeyFilter,
handler: (event: KeyboardEvent) => void,
options?: OnKeyStrokeOptions,
): () => void
export declare function onKeyStroke(
handler: (event: KeyboardEvent) => void,
options?: OnKeyStrokeOptions,
): () => void
/**
* Listen to the keydown event of the given key.
*
* @see https://vueuse.org/onKeyStroke
* @param key
* @param handler
* @param options
*/
export declare function onKeyDown(
key: KeyFilter,
handler: (event: KeyboardEvent) => void,
options?: Omit<OnKeyStrokeOptions, "eventName">,
): () => void
/**
* Listen to the keypress event of the given key.
*
* @see https://vueuse.org/onKeyStroke
* @param key
* @param handler
* @param options
*/
export declare function onKeyPressed(
key: KeyFilter,
handler: (event: KeyboardEvent) => void,
options?: Omit<OnKeyStrokeOptions, "eventName">,
): () => void
/**
* Listen to the keyup event of the given key.
*
* @see https://vueuse.org/onKeyStroke
* @param key
* @param handler
* @param options
*/
export declare function onKeyUp(
key: KeyFilter,
handler: (event: KeyboardEvent) => void,
options?: Omit<OnKeyStrokeOptions, "eventName">,
): () => void
Source ​
Contributors ​
Anthony Fu
webfansplz
Anonimus Programus
yn
David Hewson
lainbo
jack zhang
vaakian X
vaakian X
azaleta
Curt Grimes
Jelf
leovoon
Arpit
Ivan Que
Alex Kozack
yang
Changelog ​
v10.0.0-beta.4
on 4/13/20234d757
- feat(types)!: rename MaybeComputedRef
to MaybeRefOrGetter
0a72b
- feat(toValue): rename resolveUnref
to toValue
v10.0.0-beta.2
on 3/28/2023v9.10.0
on 1/3/2023v9.3.0
on 9/26/2022