Join our Discord Community

useMousePosition

A React hook for tracking mouse position with element-relative coordinates.

Loading component...

Installation

npx shadcn@latest add https://www.shadcn.io/registry/use-mouse-position.json
npx shadcn@latest add https://www.shadcn.io/registry/use-mouse-position.json
pnpm dlx shadcn@latest add https://www.shadcn.io/registry/use-mouse-position.json
bunx shadcn@latest add https://www.shadcn.io/registry/use-mouse-position.json

Usage

import { useMousePosition } from "@/hooks/use-mouse-position"

function MyComponent() {
  const [position, ref] = useMousePosition<HTMLDivElement>()

  return (
    <div ref={ref}>
      <p>Mouse position: {position.x}, {position.y}</p>
      {position.elementX && (
        <p>Relative to element: {position.elementX}, {position.elementY}</p>
      )}
    </div>
  )
}

API

useMousePosition

A hook that tracks the mouse position globally and relative to a referenced element.

Parameters

The hook accepts a generic type parameter for the HTML element type.

Returns

Returns a tuple with:

  • position: Position object containing mouse coordinates
  • ref: React ref to attach to an element for relative positioning

Position Object

type Position = {
  x: number // Global mouse X coordinate
  y: number // Global mouse Y coordinate
  elementX?: number // X coordinate relative to referenced element
  elementY?: number // Y coordinate relative to referenced element
  elementPositionX?: number // Referenced element's X position
  elementPositionY?: number // Referenced element's Y position
}