Skip to content

onKeyStroke

Category
Export Size
784 B
Last Changed
5 months ago

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

ts
import { 
onKeyStroke
} from '@vueuse/core'
onKeyStroke
('ArrowDown', (
e
) => {
e
.
preventDefault
()
})

See this table for all key codes.

Listen To Multiple Keys

ts
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

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

ts
// 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-str
oke:
c,v
="
onUpdate
"
type
="text">
<!-- with options --> <
input
v-on-key-str
oke:
c,v
="
[
onUpdate
, {
eventName
: 'keyup' }]
"
type
="text">
</template>

Custom Keyboard Event

ts
onKeyStroke
('Shift', (
e
) => {
console
.
log
('Shift key up')
}, {
eventName
: 'keyup' })

Or

ts
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'})

Type Declarations

Show Type Declarations
ts
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

SourceDemoDocs

Contributors

Anthony Fu
Anthony Fu
webfansplz
SerKo
IlyaL
Nic Mulvaney
Arthur Darkstone
Anonimus Programus
yn
David Hewson
lainbo
jack zhang
vaakian X
vaakian X
azaleta
Curt Grimes
Jelf
leovoon
Arpit
Ivan Que
Alex Kozack
yang

Changelog

v12.8.0 on
7432f - feat(types): deprecate MaybeRef and MaybeRefOrGetter in favor of Vue's native (#4636)
v12.3.0 on
59f75 - feat(toValue): deprecate toValue from @vueuse/shared in favor of Vue's native
v12.0.0-beta.1 on
0a9ed - feat!: drop Vue 2 support, optimize bundles and clean up (#4349)
v10.0.0-beta.4 on
4d757 - feat(types)!: rename MaybeComputedRef to MaybeRefOrGetter
0a72b - feat(toValue): rename resolveUnref to toValue
v10.0.0-beta.2 on
22ca5 - feat: support ignoring repeated stroke (#2652)

Released under the MIT License.

Build faster with AI
New Masterclass to help you leverage AI in your Vue workflow
Get Early Access