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