⬅️ Back to Table of Contents

📄 useMouse

📊 Analysis Summary

Metric	Count
🔧 Functions	9
📦 Imports	8
📊 Variables & Constants	1
📐 Interfaces	2
📑 Type Aliases	3

📚 Table of Contents

• Imports
• Variables & Constants
• Functions
• Interfaces
• Type Aliases

🛠️ File Location:

📂 packages/core/useMouse/index.ts

📦 Imports

Name	Source
ConfigurableEventFilter	@vueuse/shared
MaybeRefOrGetter	vue
ShallowRef	vue
ConfigurableWindow	../_configurable
Position	../types
shallowRef	vue
defaultWindow	../_configurable
useEventListener	../useEventListener

---

Variables & Constants

Name	Type	Kind	Value	Exported
UseMouseBuiltinExtractors	Record<UseMouseCoordType, UseMouseEve...	const	{ page: event => [event.pageX, event.pageY], client: event => [event.clientX,...	✗

---

Functions

useMouse(options: UseMouseOptions): UseMouseReturn

Reactive mouse position.

Parameters:

• options any: No description

See: https://vueuse.org/useMouse

Raw JSDoc

/**
 * Reactive mouse position.
 *
 * @see https://vueuse.org/useMouse
 * @param options
 */

Calls:

• shallowRef (from vue)
• extractor
• eventFilter
• mouseHandler
• touchHandler
• scrollHandler
• useEventListener (from ../useEventListener)

Code

export function useMouse(options: UseMouseOptions = {}): UseMouseReturn {
  const {
    type = 'page',
    touch = true,
    resetOnTouchEnds = false,
    initialValue = { x: 0, y: 0 },
    window = defaultWindow,
    target = window,
    scroll = true,
    eventFilter,
  } = options

  let _prevMouseEvent: MouseEvent | null = null
  let _prevScrollX = 0
  let _prevScrollY = 0

  const x = shallowRef(initialValue.x)
  const y = shallowRef(initialValue.y)
  const sourceType = shallowRef<UseMouseSourceType>(null)

  const extractor = typeof type === 'function'
    ? type
    : UseMouseBuiltinExtractors[type]

  const mouseHandler = (event: MouseEvent) => {
    const result = extractor(event)
    _prevMouseEvent = event

    if (result) {
      [x.value, y.value] = result
      sourceType.value = 'mouse'
    }

    if (window) {
      _prevScrollX = window.scrollX
      _prevScrollY = window.scrollY
    }
  }

  const touchHandler = (event: TouchEvent) => {
    if (event.touches.length > 0) {
      const result = extractor(event.touches[0])
      if (result) {
        [x.value, y.value] = result
        sourceType.value = 'touch'
      }
    }
  }

  const scrollHandler = () => {
    if (!_prevMouseEvent || !window)
      return
    const pos = extractor(_prevMouseEvent)

    if (_prevMouseEvent instanceof MouseEvent && pos) {
      x.value = pos[0] + window.scrollX - _prevScrollX
      y.value = pos[1] + window.scrollY - _prevScrollY
    }
  }

  const reset = () => {
    x.value = initialValue.x
    y.value = initialValue.y
  }

  const mouseHandlerWrapper = eventFilter
    ? (event: MouseEvent) => eventFilter(() => mouseHandler(event), {} as any)
    : (event: MouseEvent) => mouseHandler(event)

  const touchHandlerWrapper = eventFilter
    ? (event: TouchEvent) => eventFilter(() => touchHandler(event), {} as any)
    : (event: TouchEvent) => touchHandler(event)

  const scrollHandlerWrapper = eventFilter
    ? () => eventFilter(() => scrollHandler(), {} as any)
    : () => scrollHandler()

  if (target) {
    const listenerOptions = { passive: true }
    useEventListener(target, ['mousemove', 'dragover'], mouseHandlerWrapper, listenerOptions)
    if (touch && type !== 'movement') {
      useEventListener(target, ['touchstart', 'touchmove'], touchHandlerWrapper, listenerOptions)
      if (resetOnTouchEnds)
        useEventListener(target, 'touchend', reset, listenerOptions)
    }
    if (scroll && type === 'page')
      useEventListener(window, 'scroll', scrollHandlerWrapper, listenerOptions)
  }

  return {
    x,
    y,
    sourceType,
  }
}

page(event: MouseEvent | Touch): [number, number]

Parameters:

• event MouseEvent | Touch

Returns: [number, number]

Code

event => [event.pageX, event.pageY]

client(event: MouseEvent | Touch): [number, number]

Parameters:

• event MouseEvent | Touch

Returns: [number, number]

Code

event => [event.clientX, event.clientY]

screen(event: MouseEvent | Touch): [number, number]

Parameters:

• event MouseEvent | Touch

Returns: [number, number]

Code

event => [event.screenX, event.screenY]

movement(event: MouseEvent | Touch): [number, number]

Parameters:

• event MouseEvent | Touch

Returns: [number, number]

Code

event => (event instanceof MouseEvent
    ? [event.movementX, event.movementY]
    : null
  )

Internal helpers

Declared inside another function in this file.

mouseHandler(event: MouseEvent): void

Parameters:

• event MouseEvent

Returns: void

Calls:

• extractor

Code

(event: MouseEvent) => {
    const result = extractor(event)
    _prevMouseEvent = event

    if (result) {
      [x.value, y.value] = result
      sourceType.value = 'mouse'
    }

    if (window) {
      _prevScrollX = window.scrollX
      _prevScrollY = window.scrollY
    }
  }

touchHandler(event: TouchEvent): void

Parameters:

• event TouchEvent

Returns: void

Calls:

• extractor

Code

(event: TouchEvent) => {
    if (event.touches.length > 0) {
      const result = extractor(event.touches[0])
      if (result) {
        [x.value, y.value] = result
        sourceType.value = 'touch'
      }
    }
  }

scrollHandler(): void

Returns: void

Calls:

• extractor

Code

() => {
    if (!_prevMouseEvent || !window)
      return
    const pos = extractor(_prevMouseEvent)

    if (_prevMouseEvent instanceof MouseEvent && pos) {
      x.value = pos[0] + window.scrollX - _prevScrollX
      y.value = pos[1] + window.scrollY - _prevScrollY
    }
  }

reset(): void

Returns: void

Code

() => {
    x.value = initialValue.x
    y.value = initialValue.y
  }

---

Interfaces

UseMouseOptions

Interface Code

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
}

Properties

Name	Type	Optional	Description
type	UseMouseCoordType \| UseMouseEventExtractor	✓	not shown
target	MaybeRefOrGetter<Window \| EventTarget \| null \| undefined>	✓	not shown
touch	boolean	✓	not shown
scroll	boolean	✓	not shown
resetOnTouchEnds	boolean	✓	not shown
initialValue	Position	✓	not shown

UseMouseReturn

Interface Code

export interface UseMouseReturn {
  x: ShallowRef<number>
  y: ShallowRef<number>
  sourceType: ShallowRef<UseMouseSourceType>
}

Properties

Name	Type	Optional	Description
x	ShallowRef<number>	✗	not shown
y	ShallowRef<number>	✗	not shown
sourceType	ShallowRef<UseMouseSourceType>	✗	not shown

---

Type Aliases

UseMouseCoordType

type UseMouseCoordType = 'page' | 'client' | 'screen' | 'movement';

UseMouseSourceType

type UseMouseSourceType = 'mouse' | 'touch' | null;

UseMouseEventExtractor

type UseMouseEventExtractor = (event: MouseEvent | Touch) => [x: number, y: number] | null | undefined;

---

Generated by Syntax Scribe