0
# Mouse & Pointer Events
1

2
Comprehensive mouse and pointer event handling with multi-touch support, gesture detection, and advanced interaction utilities.
3

4
## Capabilities
5

6
### Mouse Tracking
7

8
#### useMouse
9

10
Reactive mouse position tracking with configurable coordinate systems.
11

12
```typescript { .api }
13
/**
14
 * Reactive mouse position tracking
15
 * @param options - Configuration options
16
 * @returns Mouse position and metadata
17
 */
18
function useMouse(options?: UseMouseOptions): {
19
  x: Ref<number>;
20
  y: Ref<number>;
21
  sourceType: Ref<UseMouseSourceType>;
22
};
23

24
interface UseMouseOptions extends ConfigurableWindow, ConfigurableEventFilter {
25
  type?: UseMouseCoordType;
26
  touch?: boolean;
27
  resetOnTouchEnds?: boolean;
28
  initialValue?: Position;
29
  target?: MaybeElementRef;
30
  scroll?: boolean;
31
}
32

33
type UseMouseCoordType = 'page' | 'client' | 'screen' | 'movement';
34
type UseMouseSourceType = 'mouse' | 'touch' | null;
35
```
36

37
**Usage Examples:**
38

39
```typescript
40
import { useMouse } from "@vueuse/core";
41

42
// Basic mouse tracking
43
const { x, y } = useMouse();
44

45
// Track relative to specific element
46
const element = ref<HTMLElement>();
47
const { x, y } = useMouse({ target: element });
48

49
// Include touch events
50
const { x, y, sourceType } = useMouse({ touch: true });
51

52
// Use different coordinate system
53
const { x, y } = useMouse({ type: 'client' }); // viewport coordinates
54
const { x, y } = useMouse({ type: 'movement' }); // movement delta
55
```
56

57
#### useMouseInElement
58

59
Reactive mouse position relative to an element.
60

61
```typescript { .api }
62
/**
63
 * Reactive mouse position relative to an element
64
 * @param target - Target element or ref
65
 * @param options - Configuration options
66
 * @returns Mouse position relative to element
67
 */
68
function useMouseInElement(
69
  target?: MaybeElementRef,
70
  options?: UseMouseInElementOptions
71
): {
72
  x: Ref<number>;
73
  y: Ref<number>;
74
  elementX: Ref<number>;
75
  elementY: Ref<number>;
76
  elementPositionX: Ref<number>;
77
  elementPositionY: Ref<number>;
78
  elementHeight: Ref<number>;
79
  elementWidth: Ref<number>;
80
  isOutside: Ref<boolean>;
81
  stop: () => void;
82
};
83

84
interface UseMouseInElementOptions extends UseMouseOptions {
85
  handleOutside?: boolean;
86
}
87
```
88

89
#### useMousePressed
90

91
Reactive mouse pressed state tracking.
92

93
```typescript { .api }
94
/**
95
 * Reactive mouse button pressed state
96
 * @param options - Configuration options
97
 * @returns Mouse pressed state and utilities
98
 */
99
function useMousePressed(options?: UseMousePressedOptions): {
100
  pressed: Ref<boolean>;
101
  sourceType: Ref<UseMouseSourceType>;
102
};
103

104
interface UseMousePressedOptions extends ConfigurableWindow {
105
  touch?: boolean;
106
  drag?: boolean;
107
  capture?: boolean;
108
  initialValue?: boolean;
109
  target?: MaybeElementRef;
110
}
111
```
112

113
### Pointer Events
114

115
#### usePointer
116

117
Reactive pointer events with multi-touch support.
118

119
```typescript { .api }
120
/**
121
 * Reactive pointer events with multi-touch support
122
 * @param options - Configuration options
123
 * @returns Pointer state and events
124
 */
125
function usePointer(options?: UsePointerOptions): {
126
  isInside: Ref<boolean>;
127
  pressure: Ref<number>;
128
  pointerId: Ref<number>;
129
  height: Ref<number>;
130
  width: Ref<number>;
131
  tiltX: Ref<number>;
132
  tiltY: Ref<number>;
133
  pointerType: Ref<string>;
134
  isPrimary: Ref<boolean>;
135
} & ReturnType<typeof useMouse>;
136

137
interface UsePointerOptions extends UseMouseOptions {
138
  pointerTypes?: PointerType[];
139
}
140
```
141

142
#### usePointerLock
143

144
Reactive Pointer Lock API management.
145

146
```typescript { .api }
147
/**
148
 * Reactive Pointer Lock API
149
 * @param target - Target element or ref
150
 * @param options - Configuration options
151
 * @returns Pointer lock state and controls
152
 */
153
function usePointerLock(
154
  target?: MaybeElementRef,
155
  options?: UsePointerLockOptions
156
): UsePointerLockReturn;
157

158
interface UsePointerLockReturn {
159
  isSupported: ComputedRef<boolean>;
160
  element: Ref<Element | null>;
161
  triggerElement: Ref<Element | null>;
162
  isActive: ComputedRef<boolean>;
163
  lock: (element?: MaybeElementRef) => Promise<Element | null>;
164
  unlock: () => Promise<boolean>;
165
}
166
```
167

168
#### usePointerSwipe
169

170
Reactive pointer swipe gesture detection.
171

172
```typescript { .api }
173
/**
174
 * Reactive pointer swipe gesture detection
175
 * @param target - Target element or ref
176
 * @param options - Configuration options
177
 * @returns Swipe detection utilities
178
 */
179
function usePointerSwipe(
180
  target: MaybeElementRef,
181
  options?: UsePointerSwipeOptions
182
): {
183
  readonly isSwiping: Ref<boolean>;
184
  readonly direction: ComputedRef<UseSwipeDirection | null>;
185
  readonly posStart: Readonly<Position>;
186
  readonly posEnd: Readonly<Position>;
187
  readonly distanceX: ComputedRef<number>;
188
  readonly distanceY: ComputedRef<number>;
189
  stop: () => void;
190
};
191

192
interface UsePointerSwipeOptions {
193
  threshold?: number;
194
  onSwipe?: (e: PointerEvent) => void;
195
  onSwipeEnd?: (e: PointerEvent, direction: UseSwipeDirection) => void;
196
  onSwipeStart?: (e: PointerEvent) => void;
197
  disableTextSelection?: boolean;
198
  pointerTypes?: PointerType[];
199
}
200

201
type UseSwipeDirection = 'up' | 'down' | 'left' | 'right';
202
```
203

204
### Drag & Drop
205

206
#### useDraggable
207

208
Make elements draggable with reactive position tracking.
209

210
```typescript { .api }
211
/**
212
 * Make elements draggable with reactive position tracking
213
 * @param target - Target element or ref
214
 * @param options - Configuration options
215
 * @returns Draggable state and utilities
216
 */
217
function useDraggable(
218
  target: MaybeComputedElementRef,
219
  options?: UseDraggableOptions
220
): {
221
  x: Ref<number>;
222
  y: Ref<number>;
223
  isDragging: Ref<boolean>;
224
  position: ComputedRef<Position>;
225
  style: ComputedRef<CSSProperties>;
226
};
227

228
interface UseDraggableOptions {
229
  exact?: boolean;
230
  preventDefault?: boolean;
231
  stopPropagation?: boolean;
232
  pointerTypes?: PointerType[];
233
  initialValue?: Position;
234
  onStart?: (position: Position, event: PointerEvent) => void | false;
235
  onMove?: (position: Position, event: PointerEvent) => void;
236
  onEnd?: (position: Position, event: PointerEvent) => void;
237
  axis?: 'x' | 'y' | 'both';
238
  disabled?: MaybeRefOrGetter<boolean>;
239
  containerElement?: MaybeElementRef;
240
  handle?: MaybeElementRef;
241
}
242
```
243

244
**Usage Examples:**
245

246
```typescript
247
import { ref } from "vue";
248
import { useDraggable } from "@vueuse/core";
249

250
const el = ref<HTMLElement>();
251

252
// Basic draggable
253
const { x, y, isDragging } = useDraggable(el);
254

255
// Constrain to axis
256
const { x, y } = useDraggable(el, { axis: 'x' });
257

258
// With drag handles and containers
259
const container = ref<HTMLElement>();
260
const handle = ref<HTMLElement>();
261

262
const { x, y } = useDraggable(el, {
263
  containerElement: container,
264
  handle: handle
265
});
266

267
// With callbacks
268
const { x, y } = useDraggable(el, {
269
  onStart: (pos, event) => {
270
    console.log('Drag started at', pos);
271
  },
272
  onMove: (pos, event) => {
273
    console.log('Dragging to', pos);
274
  },
275
  onEnd: (pos, event) => {
276
    console.log('Drag ended at', pos);
277
  }
278
});
279
```
280

281
#### useDropZone
282

283
Create drop zone for file uploads and drag & drop operations.
284

285
```typescript { .api }
286
/**
287
 * Create drop zone for file uploads and drag & drop
288
 * @param target - Target element or ref
289
 * @param options - Configuration options
290
 * @returns Drop zone state and utilities
291
 */
292
function useDropZone(
293
  target: MaybeElementRef,
294
  options?: UseDropZoneOptions
295
): UseDropZoneReturn;
296

297
interface UseDropZoneReturn {
298
  files: Ref<File[] | null>;
299
  isOverDropZone: Ref<boolean>;
300
}
301

302
interface UseDropZoneOptions {
303
  onDrop?: (files: File[] | null, event: DragEvent) => void;
304
  onEnter?: (files: File[] | null, event: DragEvent) => void;
305
  onLeave?: (files: File[] | null, event: DragEvent) => void;
306
  onOver?: (files: File[] | null, event: DragEvent) => void;
307
  dataTypes?: string[];
308
  preventDefaultForUnhandled?: boolean;
309
}
310
```
311

312
### Gesture Recognition
313

314
#### useSwipe
315

316
Reactive swipe gesture detection for touch and mouse.
317

318
```typescript { .api }
319
/**
320
 * Reactive swipe gesture detection
321
 * @param target - Target element or ref
322
 * @param options - Configuration options
323
 * @returns Swipe detection utilities
324
 */
325
function useSwipe(
326
  target: MaybeElementRef,
327
  options?: UseSwipeOptions
328
): UseSwipeReturn;
329

330
interface UseSwipeReturn {
331
  isPressed: Ref<boolean>;
332
  isSwiping: Ref<boolean>;
333
  direction: ComputedRef<UseSwipeDirection | null>;
334
  coordsStart: Readonly<Position>;
335
  coordsEnd: Readonly<Position>;
336
  lengthX: ComputedRef<number>;
337
  lengthY: ComputedRef<number>;
338
  stop: () => void;
339
}
340

341
interface UseSwipeOptions {
342
  threshold?: number;
343
  onSwipe?: (e: TouchEvent | MouseEvent) => void;
344
  onSwipeEnd?: (e: TouchEvent | MouseEvent, direction: UseSwipeDirection) => void;
345
  onSwipeStart?: (e: TouchEvent | MouseEvent) => void;
346
  passive?: boolean;
347
  window?: Window;
348
}
349
```
350

351
#### onLongPress
352

353
Listen for long press events on elements.
354

355
```typescript { .api }
356
/**
357
 * Listen for long press events
358
 * @param target - Target element or ref
359
 * @param handler - Long press handler function
360
 * @param options - Configuration options
361
 * @returns Stop function
362
 */
363
function onLongPress(
364
  target: MaybeElementRef,
365
  handler: (evt: PointerEvent) => void,
366
  options?: OnLongPressOptions
367
): () => void;
368

369
interface OnLongPressOptions {
370
  delay?: number;
371
  modifiers?: OnLongPressModifiers;
372
  distanceThreshold?: number | false;
373
}
374

375
interface OnLongPressModifiers {
376
  stop?: boolean;
377
  once?: boolean;
378
  prevent?: boolean;
379
  capture?: boolean;
380
  self?: boolean;
381
}
382
```
383

384
### Advanced Interactions
385

386
#### useParallax
387

388
Create parallax effects based on mouse movement.
389

390
```typescript { .api }
391
/**
392
 * Create parallax effects based on mouse movement
393
 * @param target - Target element or ref
394
 * @param options - Configuration options
395
 * @returns Parallax transforms
396
 */
397
function useParallax(
398
  target: MaybeElementRef,
399
  options?: UseParallaxOptions
400
): UseParallaxReturn;
401

402
interface UseParallaxReturn {
403
  tilt: ComputedRef<number>;
404
  roll: ComputedRef<number>;
405
  source: 'mouse' | 'deviceOrientation';
406
}
407

408
interface UseParallaxOptions {
409
  deviceOrientationTiltAdjust?: (i: number) => number;
410
  deviceOrientationRollAdjust?: (i: number) => number;
411
  mouseTiltAdjust?: (i: number) => number;
412
  mouseRollAdjust?: (i: number) => number;
413
}
414
```
415

416
## Shared Types
417

418
```typescript { .api }
419
interface Position {
420
  x: number;
421
  y: number;
422
}
423

424
type PointerType = 'mouse' | 'touch' | 'pen';
425

426
interface ConfigurableEventFilter {
427
  eventFilter?: EventFilter;
428
}
429

430
type EventFilter<Args extends any[] = any[], This = any, Return = void> = (
431
  invoke: Fn<Args, Return>,
432
  options: FunctionWrapperOptions<Args, This>
433
) => void;
434
```