1---
2category: Sensors
3variants: onKeyDown, onKeyUp, onKeyPressed
4---
5 
6# onKeyStroke
7 
8Listen for keyboard keystrokes. By default, listens on `keydown` events on `window`.
9 
10## Usage
11 
12```ts
13import { onKeyStroke } from '@vueuse/core'
14 
15onKeyStroke('ArrowDown', (e) => {
16  e.preventDefault()
17})
18```
19 
20See [this table](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values) for all key codes.
21 
22### Return Value
23 
24Returns a stop function to remove the event listener.
25 
26```ts
27const stop = onKeyStroke('Escape', handler)
28 
29// Later, stop listening
30stop()
31```
32 
33### Listen To Multiple Keys
34 
35```ts
36import { onKeyStroke } from '@vueuse/core'
37 
38onKeyStroke(['s', 'S', 'ArrowDown'], (e) => {
39  e.preventDefault()
40})
41 
42// listen to all keys by passing `true` or skipping the key parameter
43onKeyStroke(true, (e) => {
44  e.preventDefault()
45})
46onKeyStroke((e) => {
47  e.preventDefault()
48})
49```
50 
51### Custom Key Predicate
52 
53You can pass a custom function to determine which keys should trigger the handler.
54 
55```ts
56import { onKeyStroke } from '@vueuse/core'
57 
58onKeyStroke(
59  e => e.key === 'A' && e.shiftKey,
60  (e) => {
61    console.log('Shift+A pressed')
62  },
63)
64```
65 
66### Custom Event Target
67 
68```ts
69import { onKeyStroke } from '@vueuse/core'
70 
71onKeyStroke('A', (e) => {
72  console.log('Key A pressed on document')
73}, { target: document })
74```
75 
76### Ignore Repeated Events
77 
78The callback will trigger only once when pressing `A` and **holding down**. The `dedupe` option can also be a reactive ref.
79 
80```ts
81import { onKeyStroke } from '@vueuse/core'
82 
83onKeyStroke('A', (e) => {
84  console.log('Key A pressed')
85}, { dedupe: true })
86```
87 
88Reference: [KeyboardEvent.repeat](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/repeat)
89 
90### Passive Mode
91 
92Set `passive: true` to use a passive event listener.
93 
94```ts
95import { onKeyStroke } from '@vueuse/core'
96 
97onKeyStroke('A', handler, { passive: true })
98```
99 
100## Directive Usage
101 
102```vue
103<script setup lang="ts">
104import { vOnKeyStroke } from '@vueuse/components'
105 
106function onUpdate(e: KeyboardEvent) {
107  // impl...
108}
109</script>
110 
111<template>
112  <input v-on-key-stroke:c,v="onUpdate" type="text">
113  <!-- with options -->
114  <input v-on-key-stroke:c,v="[onUpdate, { eventName: 'keyup' }]" type="text">
115</template>
116```
117 
118### Custom Keyboard Event
119 
120```ts
121import { onKeyStroke } from '@vueuse/core'
122// ---cut---
123onKeyStroke('Shift', (e) => {
124  console.log('Shift key up')
125}, { eventName: 'keyup' })
126```
127 
128Or
129 
130```ts
131import { onKeyUp } from '@vueuse/core'
132// ---cut---
133onKeyUp('Shift', () => console.log('Shift key up'))
134```
135 
136## Shorthands
137 
138- `onKeyDown` - alias for `onKeyStroke(key, handler, {eventName: 'keydown'})`
139- `onKeyPressed` - alias for `onKeyStroke(key, handler, {eventName: 'keypress'})`
140- `onKeyUp` - alias for `onKeyStroke(key, handler, {eventName: 'keyup'})`
141 
142## Type Declarations
143 
144```ts
145export type KeyPredicate = (event: KeyboardEvent) => boolean
146export type KeyFilter = true | string | string[] | KeyPredicate
147export type KeyStrokeEventName = "keydown" | "keypress" | "keyup"
148export interface OnKeyStrokeOptions {
149  eventName?: KeyStrokeEventName
150  target?: MaybeRefOrGetter<EventTarget | null | undefined>
151  passive?: boolean
152  /**
153   * Set to `true` to ignore repeated events when the key is being held down.
154   *
155   * @default false
156   */
157  dedupe?: MaybeRefOrGetter<boolean>
158}
159/**
160 * Listen for keyboard keystrokes.
161 *
162 * @see https://vueuse.org/onKeyStroke
163 */
164export declare function onKeyStroke(
165  key: KeyFilter,
166  handler: (event: KeyboardEvent) => void,
167  options?: OnKeyStrokeOptions,
168): () => void
169export declare function onKeyStroke(
170  handler: (event: KeyboardEvent) => void,
171  options?: OnKeyStrokeOptions,
172): () => void
173/**
174 * Listen to the keydown event of the given key.
175 *
176 * @see https://vueuse.org/onKeyStroke
177 * @param key
178 * @param handler
179 * @param options
180 */
181export declare function onKeyDown(
182  key: KeyFilter,
183  handler: (event: KeyboardEvent) => void,
184  options?: Omit<OnKeyStrokeOptions, "eventName">,
185): () => void
186/**
187 * Listen to the keypress event of the given key.
188 *
189 * @see https://vueuse.org/onKeyStroke
190 * @param key
191 * @param handler
192 * @param options
193 */
194export declare function onKeyPressed(
195  key: KeyFilter,
196  handler: (event: KeyboardEvent) => void,
197  options?: Omit<OnKeyStrokeOptions, "eventName">,
198): () => void
199/**
200 * Listen to the keyup event of the given key.
201 *
202 * @see https://vueuse.org/onKeyStroke
203 * @param key
204 * @param handler
205 * @param options
206 */
207export declare function onKeyUp(
208  key: KeyFilter,
209  handler: (event: KeyboardEvent) => void,
210  options?: Omit<OnKeyStrokeOptions, "eventName">,
211): () => void
212```
213