⬅️ Back to Table of Contents

📄 useMouseInElement

📊 Analysis Summary

Metric	Count
🔧 Functions	3
📦 Imports	13
🟢 Vue Composition API	1
📐 Interfaces	2

📚 Table of Contents

• Imports
• Vue Composition API
• Functions
• Interfaces

🛠️ File Location:

📂 packages/core/useMouseInElement/index.ts

📦 Imports

Name	Source
ShallowRef	vue
MaybeElementRef	../unrefElement
UseMouseOptions	../useMouse
UseMouseReturn	../useMouse
tryOnMounted	@vueuse/shared
shallowRef	vue
watch	vue
defaultWindow	../_configurable
unrefElement	../unrefElement
useEventListener	../useEventListener
useMouse	../useMouse
useMutationObserver	../useMutationObserver
useResizeObserver	../useResizeObserver

---

Vue Composition API

Name	Type	Reactive Variables	Composables
watch	watch	none	none

---

Functions

useMouseInElement(target: MaybeElementRef, options: MouseInElementOptions): { x: ShallowRef<number>; y: ShallowRef<number>; sourceType:…

Reactive mouse position related to an element.

Parameters:

• target any: No description
• options any: No description

See: https://vueuse.org/useMouseInElement

Raw JSDoc

/**
 * Reactive mouse position related to an element.
 *
 * @see https://vueuse.org/useMouseInElement
 * @param target
 * @param options
 */

Calls:

• useMouse (from ../useMouse)
• shallowRef (from vue)
• unrefElement (from ../unrefElement)
• el.getClientRects
• stopFnList.forEach
• fn
• tryOnMounted (from @vueuse/shared)
• update
• useResizeObserver (from ../useResizeObserver)
• useMutationObserver (from ../useMutationObserver)
• watch (from vue)
• stopFnList.push
• useEventListener (from ../useEventListener)

Code

export function useMouseInElement(
  target?: MaybeElementRef,
  options: MouseInElementOptions = {},
) {
  const {
    windowResize = true,
    windowScroll = true,
    handleOutside = true,
    window = defaultWindow,
  } = options
  const type = options.type || 'page'

  const { x, y, sourceType } = useMouse(options)

  const targetRef = shallowRef(target ?? window?.document.body)
  const elementX = shallowRef(0)
  const elementY = shallowRef(0)
  const elementPositionX = shallowRef(0)
  const elementPositionY = shallowRef(0)
  const elementHeight = shallowRef(0)
  const elementWidth = shallowRef(0)
  const isOutside = shallowRef(true)

  function update() {
    if (!window)
      return

    const el = unrefElement(targetRef)
    if (!el || !(el instanceof Element))
      return

    for (const rect of el.getClientRects()) {
      const {
        left,
        top,
        width,
        height,
      } = rect

      elementPositionX.value = left + (type === 'page' ? window.pageXOffset : 0)
      elementPositionY.value = top + (type === 'page' ? window.pageYOffset : 0)
      elementHeight.value = height
      elementWidth.value = width

      const elX = x.value - elementPositionX.value
      const elY = y.value - elementPositionY.value
      isOutside.value = width === 0 || height === 0
        || elX < 0 || elY < 0
        || elX > width || elY > height

      if (handleOutside || !isOutside.value) {
        elementX.value = elX
        elementY.value = elY
      }

      if (!isOutside.value)
        break
    }
  }

  const stopFnList: Array<() => void> = []
  function stop() {
    stopFnList.forEach(fn => fn())
    stopFnList.length = 0
  }

  tryOnMounted(() => {
    update()
  })

  if (window) {
    const {
      stop: stopResizeObserver,
    } = useResizeObserver(targetRef, update)
    const {
      stop: stopMutationObserver,
    } = useMutationObserver(targetRef, update, {
      attributeFilter: ['style', 'class'],
    })

    const stopWatch = watch(
      [targetRef, x, y],
      update,
    )

    stopFnList.push(
      stopResizeObserver,
      stopMutationObserver,
      stopWatch,
    )

    useEventListener(
      document,
      'mouseleave',
      () => isOutside.value = true,
      { passive: true },
    )

    if (windowScroll) {
      stopFnList.push(
        useEventListener('scroll', update, { capture: true, passive: true }),
      )
    }
    if (windowResize) {
      stopFnList.push(
        useEventListener('resize', update, { passive: true }),
      )
    }
  }

  return {
    x,
    y,
    sourceType,
    elementX,
    elementY,
    elementPositionX,
    elementPositionY,
    elementHeight,
    elementWidth,
    isOutside,
    stop,
  }
}

Internal helpers

Declared inside another function in this file.

update(): void

Returns: void

Calls:

• unrefElement (from ../unrefElement)
• el.getClientRects

Code

function update() {
    if (!window)
      return

    const el = unrefElement(targetRef)
    if (!el || !(el instanceof Element))
      return

    for (const rect of el.getClientRects()) {
      const {
        left,
        top,
        width,
        height,
      } = rect

      elementPositionX.value = left + (type === 'page' ? window.pageXOffset : 0)
      elementPositionY.value = top + (type === 'page' ? window.pageYOffset : 0)
      elementHeight.value = height
      elementWidth.value = width

      const elX = x.value - elementPositionX.value
      const elY = y.value - elementPositionY.value
      isOutside.value = width === 0 || height === 0
        || elX < 0 || elY < 0
        || elX > width || elY > height

      if (handleOutside || !isOutside.value) {
        elementX.value = elX
        elementY.value = elY
      }

      if (!isOutside.value)
        break
    }
  }

stop(): void

Returns: void

Calls:

• stopFnList.forEach
• fn

Code

function stop() {
    stopFnList.forEach(fn => fn())
    stopFnList.length = 0
  }

---

Interfaces

MouseInElementOptions

Interface Code

export interface MouseInElementOptions extends UseMouseOptions {
  /**
   * Whether to handle mouse events when the cursor is outside the target element.
   * When enabled, mouse position will continue to be tracked even when outside the element bounds.
   *
   * @default true
   */
  handleOutside?: boolean

  /**
   * Listen to window resize event
   *
   * @default true
   */
  windowScroll?: boolean

  /**
   * Listen to window scroll event
   *
   * @default true
   */
  windowResize?: boolean
}

Properties

Name	Type	Optional	Description
handleOutside	boolean	✓	not shown
windowScroll	boolean	✓	not shown
windowResize	boolean	✓	not shown

UseMouseInElementReturn

Interface Code

export interface UseMouseInElementReturn extends UseMouseReturn {
  elementX: ShallowRef<number>
  elementY: ShallowRef<number>
  elementPositionX: ShallowRef<number>
  elementPositionY: ShallowRef<number>
  elementHeight: ShallowRef<number>
  elementWidth: ShallowRef<number>
  isOutside: ShallowRef<boolean>
  stop: () => void
}

Properties

Name	Type	Optional	Description
elementX	ShallowRef<number>	✗	not shown
elementY	ShallowRef<number>	✗	not shown
elementPositionX	ShallowRef<number>	✗	not shown
elementPositionY	ShallowRef<number>	✗	not shown
elementHeight	ShallowRef<number>	✗	not shown
elementWidth	ShallowRef<number>	✗	not shown
isOutside	ShallowRef<boolean>	✗	not shown
stop	() => void	✗	not shown

---

Generated by Syntax Scribe