0
# Browser Event Handlers
1

2
Components and directives for handling browser events like clicks, key presses, and long press gestures.
3

4
## Capabilities
5

6
### OnClickOutside Component
7

8
Detects clicks outside of the wrapped element and emits trigger events.
9

10
```typescript { .api }
11
/**
12
 * Component that detects clicks outside the wrapped element
13
 * @example
14
 * <OnClickOutside @trigger="handleClickOutside">
15
 *   <div>Click outside this to trigger event</div>
16
 * </OnClickOutside>
17
 */
18
interface OnClickOutsideProps extends RenderableComponent {
19
  /** Options for configuring click outside behavior */
20
  options?: OnClickOutsideOptions;
21
}
22

23
interface OnClickOutsideOptions {
24
  /** List of elements that should not trigger the event */
25
  ignore?: MaybeRefOrGetter<(MaybeElementRef | string)[]>;
26
  /** Use capturing phase for internal event listener @default true */
27
  capture?: boolean;
28
  /** Run handler function if focus moves to an iframe @default false */
29
  detectIframe?: boolean;
30
  /** Window object to listen on @default defaultWindow */
31
  window?: Window;
32
}
33

34
/** Component events */
35
interface OnClickOutsideEmits {
36
  /** Triggered when click occurs outside the element */
37
  trigger: (event: PointerEvent | FocusEvent) => void;
38
}
39
```
40

41
**Usage Examples:**
42

43
```vue
44
<template>
45
  <!-- Basic usage -->
46
  <OnClickOutside @trigger="handleClickOutside">
47
    <div class="modal">Modal content</div>
48
  </OnClickOutside>
49

50
  <!-- With options -->
51
  <OnClickOutside 
52
    @trigger="handleClickOutside" 
53
    :options="{ ignore: ['.ignore-element'], detectIframe: true }"
54
  >
55
    <div class="dropdown">Dropdown content</div>
56
  </OnClickOutside>
57

58
  <!-- Custom wrapper element -->
59
  <OnClickOutside as="section" @trigger="handleClickOutside">
60
    <div>Custom section wrapper</div>
61
  </OnClickOutside>
62
</template>
63

64
<script setup>
65
import { OnClickOutside } from '@vueuse/components';
66

67
function handleClickOutside(event) {
68
  console.log('Clicked outside!', event);
69
}
70
</script>
71
```
72

73
### vOnClickOutside Directive
74

75
Directive for click outside detection without component wrapper.
76

77
```typescript { .api }
78
/**
79
 * Directive for detecting clicks outside an element
80
 * @example
81
 * <div v-on-click-outside="handler">Content</div>
82
 * <div v-on-click-outside="[handler, options]">With options</div>
83
 */
84
type OnClickOutsideHandler = (event: PointerEvent | FocusEvent) => void;
85

86
interface VOnClickOutsideValue {
87
  /** Simple handler function */
88
  handler: OnClickOutsideHandler;
89
  /** Handler with options tuple */
90
  handlerWithOptions: [OnClickOutsideHandler, OnClickOutsideOptions];
91
}
92

93
/** Directive modifiers */
94
interface OnClickOutsideModifiers {
95
  /** Disable capture mode (use bubble instead) */
96
  bubble: boolean;
97
}
98
```
99

100
**Usage Examples:**
101

102
```vue
103
<template>
104
  <!-- Simple usage -->
105
  <div v-on-click-outside="handleClickOutside">
106
    Click outside me
107
  </div>
108

109
  <!-- With options -->
110
  <div v-on-click-outside="[handleClickOutside, { capture: false }]">
111
    With custom options
112
  </div>
113

114
  <!-- Using bubble modifier -->
115
  <div v-on-click-outside.bubble="handleClickOutside">
116
    Using bubble phase
117
  </div>
118
</template>
119

120
<script setup>
121
import { vOnClickOutside } from '@vueuse/components';
122

123
function handleClickOutside(event) {
124
  console.log('Clicked outside!', event);
125
}
126
</script>
127
```
128

129
### vOnKeyStroke Directive
130

131
Directive for keyboard event handling.
132

133
```typescript { .api }
134
/**
135
 * Directive for handling keyboard events
136
 * @example
137
 * <input v-on-key-stroke:enter="handleEnter" />
138
 * <div v-on-key-stroke="[handleKey, { eventName: 'keydown' }]">
139
 */
140
type OnKeyStrokeHandler = (event: KeyboardEvent) => void;
141

142
interface OnKeyStrokeOptions {
143
  /** Key or keys to listen for */
144
  key?: string | string[];
145
  /** Event name to listen for @default 'keydown' */
146
  eventName?: 'keydown' | 'keypress' | 'keyup';
147
  /** Target element @default window */
148
  target?: MaybeRefOrGetter<EventTarget | null | undefined>;
149
  /** Auto-repeat behavior @default false */
150
  autoRepeat?: boolean;
151
  /** Window object @default defaultWindow */
152
  window?: Window;
153
}
154

155
interface VOnKeyStrokeValue {
156
  /** Simple handler function */
157
  handler: OnKeyStrokeHandler;
158
  /** Handler with options tuple */
159
  handlerWithOptions: [OnKeyStrokeHandler, OnKeyStrokeOptions];
160
}
161
```
162

163
**Usage Examples:**
164

165
```vue
166
<template>
167
  <!-- Listen for Enter key -->
168
  <input v-on-key-stroke:enter="handleEnter" />
169

170
  <!-- Listen for Escape key -->
171
  <div v-on-key-stroke:escape="handleEscape">
172
    Press Escape
173
  </div>
174

175
  <!-- With options -->
176
  <div v-on-key-stroke="[handleKeyDown, { key: 'Space', eventName: 'keyup' }]">
177
    Custom key handling
178
  </div>
179

180
  <!-- Multiple keys -->
181
  <input v-on-key-stroke="[handleKeys, { key: ['Enter', 'Tab'] }]" />
182
</template>
183

184
<script setup>
185
import { vOnKeyStroke } from '@vueuse/components';
186

187
function handleEnter(event) {
188
  console.log('Enter pressed', event);
189
}
190

191
function handleEscape(event) {
192
  console.log('Escape pressed', event);
193
}
194

195
function handleKeyDown(event) {
196
  console.log('Space released', event);
197
}
198

199
function handleKeys(event) {
200
  console.log('Enter or Tab pressed', event);
201
}
202
</script>
203
```
204

205
### OnLongPress Component
206

207
Detects long press gestures and emits trigger events.
208

209
```typescript { .api }
210
/**
211
 * Component that detects long press gestures
212
 * @example
213
 * <OnLongPress @trigger="handleLongPress" :options="{ delay: 500 }">
214
 *   <button>Long press me</button>
215
 * </OnLongPress>
216
 */
217
interface OnLongPressProps extends RenderableComponent {
218
  /** Options for configuring long press behavior */
219
  options?: OnLongPressOptions;
220
}
221

222
interface OnLongPressOptions {
223
  /** Delay in ms before trigger @default 500 */
224
  delay?: number;
225
  /** Modifiers that need to be pressed */
226
  modifiers?: OnLongPressModifiers;
227
  /** Prevent context menu @default true */
228
  preventContextMenu?: boolean;
229
}
230

231
interface OnLongPressModifiers {
232
  stop?: boolean;
233
  once?: boolean;
234
  prevent?: boolean;
235
  capture?: boolean;
236
  self?: boolean;
237
}
238

239
/** Component events */
240
interface OnLongPressEmits {
241
  /** Triggered when long press is detected */
242
  trigger: (event: PointerEvent) => void;
243
}
244
```
245

246
**Usage Examples:**
247

248
```vue
249
<template>
250
  <!-- Basic usage -->
251
  <OnLongPress @trigger="handleLongPress">
252
    <button>Long press this button</button>
253
  </OnLongPress>
254

255
  <!-- Custom delay -->
256
  <OnLongPress @trigger="handleLongPress" :options="{ delay: 1000 }">
257
    <button>Hold for 1 second</button>
258
  </OnLongPress>
259

260
  <!-- With modifiers -->
261
  <OnLongPress 
262
    @trigger="handleLongPress" 
263
    :options="{ 
264
      delay: 300, 
265
      modifiers: { prevent: true, stop: true },
266
      preventContextMenu: false 
267
    }"
268
  >
269
    <button>Custom long press</button>
270
  </OnLongPress>
271
</template>
272

273
<script setup>
274
import { OnLongPress } from '@vueuse/components';
275

276
function handleLongPress(event) {
277
  console.log('Long press detected!', event);
278
}
279
</script>
280
```
281

282
### vOnLongPress Directive
283

284
Directive for long press detection without component wrapper.
285

286
```typescript { .api }
287
/**
288
 * Directive for detecting long press gestures
289
 * @example
290
 * <button v-on-long-press="handler">Long press me</button>
291
 * <div v-on-long-press="[handler, { delay: 1000 }]">Custom delay</div>
292
 */
293
type OnLongPressHandler = (event: PointerEvent) => void;
294

295
interface VOnLongPressValue {
296
  /** Simple handler function */
297
  handler: OnLongPressHandler;
298
  /** Handler with options tuple */
299
  handlerWithOptions: [OnLongPressHandler, OnLongPressOptions];
300
}
301
```
302

303
**Usage Examples:**
304

305
```vue
306
<template>
307
  <!-- Simple usage -->
308
  <button v-on-long-press="handleLongPress">
309
    Long press me
310
  </button>
311

312
  <!-- With custom delay -->
313
  <div v-on-long-press="[handleLongPress, { delay: 800 }]">
314
    Hold for 800ms
315
  </div>
316

317
  <!-- Prevent context menu -->
318
  <img 
319
    v-on-long-press="[handleLongPress, { preventContextMenu: false }]" 
320
    src="image.jpg" 
321
    alt="Long press to save"
322
  />
323
</template>
324

325
<script setup>
326
import { vOnLongPress } from '@vueuse/components';
327

328
function handleLongPress(event) {
329
  console.log('Long press detected!', event);
330
}
331
</script>
332
```
333

334
## Type Definitions
335

336
```typescript { .api }
337
/** Common types used across browser event handlers */
338
type MaybeElementRef = HTMLElement | null | undefined;
339
type MaybeRefOrGetter<T> = T | Ref<T> | (() => T);
340

341
interface RenderableComponent {
342
  /** The element that the component should be rendered as @default 'div' */
343
  as?: object | string;
344
}
345
```