Skip to content

useMouse

Category
Export Size
1.08 kB
Last Changed
5 months ago

Reactive mouse position

Demo

Basic Usage

x: 0
y: 0
sourceType: null

Extractor Usage

x: 0
y: 0
sourceType: null

Basic Usage

ts
import { 
useMouse
} from '@vueuse/core'
const {
x
,
y
,
sourceType
} =
useMouse
()

Touch is enabled by default. To only detect mouse changes, set touch to false. The dragover event is used to track mouse position while dragging.

ts
const { 
x
,
y
} =
useMouse
({
touch
: false })

Custom Extractor

It's also possible to provide a custom extractor function to get the position from the event.

ts
import type { 
UseMouseEventExtractor
} from '@vueuse/core'
import {
useMouse
,
useParentElement
} from '@vueuse/core'
const
parentEl
=
useParentElement
()
const
extractor
:
UseMouseEventExtractor
=
event
=> (
event
instanceof
MouseEvent
? [
event
.
offsetX
,
event
.
offsetY
]
: null ) const {
x
,
y
,
sourceType
} =
useMouse
({
target
:
parentEl
,
type
:
extractor
})
js
import { useMouse, useParentElement } from '@vueuse/core'
const parentEl = useParentElement()
const extractor = (event) =>
  event instanceof MouseEvent ? [event.offsetX, event.offsetY] : null
const { x, y, sourceType } = useMouse({ target: parentEl, type: extractor })

Component Usage

This function also provides a renderless component version via the @vueuse/components package. Learn more about the usage.

vue
<template>
  <UseMouse v-slot="{ 
x
,
y
}">
x: {{
x
}}
y: {{
y
}}
</UseMouse> </template>

Type Declarations

Show Type Declarations
ts
export type 
UseMouseCoordType
= "page" | "client" | "screen" | "movement"
export type
UseMouseSourceType
= "mouse" | "touch" | null
export type
UseMouseEventExtractor
= (
event
: MouseEvent | Touch,
) => [
x
: number,
y
: number] | null | undefined
export interface UseMouseOptions extends ConfigurableWindow, ConfigurableEventFilter { /** * Mouse position based by page, client, screen, or relative to previous position * * @default 'page' */
type
?:
UseMouseCoordType
|
UseMouseEventExtractor
/** * Listen events on `target` element * * @default 'Window' */
target
?:
MaybeRefOrGetter
<Window | EventTarget | null | undefined>
/** * Listen to `touchmove` events * * @default true */
touch
?: boolean
/** * Listen to `scroll` events on window, only effective on type `page` * * @default true */
scroll
?: boolean
/** * Reset to initial value when `touchend` event fired * * @default false */
resetOnTouchEnds
?: boolean
/** * Initial values */
initialValue
?:
Position
} /** * Reactive mouse position. * * @see https://vueuse.org/useMouse * @param options */ export declare function
useMouse
(
options
?: UseMouseOptions): {
x
:
ShallowRef
<number, number>
y
:
ShallowRef
<number, number>
sourceType
:
ShallowRef
<
UseMouseSourceType
,
UseMouseSourceType
>
} export type
UseMouseReturn
=
ReturnType
<typeof
useMouse
>

Source

SourceDemoDocs

Contributors

Anthony Fu
Robin
Anthony Fu
青椒肉丝
Jelf
IlyaL
Fernando Fernández
Robin
Eduardo Luiz Schilling
karukenert
Cats Juice
丶远方
RAX7
François Lévesque
vaakian X
Sergey Danilchenko
lzdFeiFei
Scott Bedard
Marshall Thompson
Shinigami
wheat
Alex Kozack
Antério Vieira

Changelog

v12.8.0 on
7432f - feat(types): deprecate MaybeRef and MaybeRefOrGetter in favor of Vue's native (#4636)
v12.6.0 on
ce9e5 - fix: check for MouseEvent instead of Touch to work with FF (#4457)
v12.4.0 on
dd316 - feat: use passive event handlers everywhere is possible (#4477)
v12.0.0-beta.1 on
0a9ed - feat!: drop Vue 2 support, optimize bundles and clean up (#4349)
v11.3.0 on
cceeb - fix: correct spelling error (#4348)
e8d11 - fix: record the previous scroll value (#4244)
v10.4.0 on
c2f64 - fix: position won't be changed on page scroll when type is page, closes #2922 (#3244)
v10.1.0 on
4bb5b - feat: support custom event extractor (#2991)
v10.0.0-beta.4 on
39d18 - feat: support type: screen (#2467)

Released under the MIT License.

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