use-mouse (use-mouse)

Tracks the mouse position in the element and document.

v0.1.0

Usage

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

"use client";

import { RefObject, useRef, useState } from "react";

import {
  Card,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@/components/ui/card";
import { Checkbox } from "@/components/ui/checkbox";

import { useMouse } from "@/components/hooks/use-mouse";

export function UseMouseDemo() {
  const ref = useRef<HTMLDivElement>(null);
  const [trackOutside, setTrackOutside] = useState(false);
  const [clampToZero, setClampToZero] = useState(false);
  const { docX, docY, posX, posY, elX, elY, elW, elH } = useMouse({
    ref: ref as RefObject<HTMLElement>,
    trackOutside,
    clampToZero,
  });

  return (
    <Card className="relative max-w-md w-full" ref={ref}>
      <CardHeader>
        <CardTitle>useMouse</CardTitle>
        <CardDescription>
          This component uses the <code>useMouse</code> hook to track the mouse
          position.
        </CardDescription>
      </CardHeader>
      <CardContent className="space-y-2">
        <div className="flex items-center gap-2">
          <Checkbox
            checked={trackOutside}
            onCheckedChange={() => setTrackOutside((v) => !v)}
          />
          <label htmlFor="trackOutside">Track outside</label>
        </div>
        <div className="flex items-center gap-2">
          <Checkbox
            checked={clampToZero}
            onCheckedChange={() => setClampToZero((v) => !v)}
          />
          <label htmlFor="clampToZero">Clamp to zero</label>
        </div>
        <div className="space-y-2">
          <p className="text-sm">
            Mouse position in document - x:{docX} y:{docY}
          </p>
          <p className="text-sm">
            Mouse position in element - x:{elX} y:{elY}
          </p>
          <p className="text-sm">
            Element position- x:{posX} y:{posY}
          </p>
          <p className="text-sm">
            Element dimensions - {elW}x{elH}
          </p>
        </div>
      </CardContent>
      <CardFooter>
        <p className="text-sm text-muted-foreground">
          Try moving your mouse around the screen.
        </p>
      </CardFooter>
    </Card>
  );
}

Install

npx wkkkis-hooks add use-mouse

Options

Name	Type	Default	Description
ref	RefObject<HTMLElement>	null	The ref of the element to track the mouse position
trackOutside?	boolean	false	Update state even outside the element
clampToZero?	boolean	false	Clamps elX/elY to >= 0

Returns — Properties

Name	Type	Default	Description
The	—	—	hook returns an object with mouse position in the document, relative to the element, and element dimensions.

Required Ref & Error Handling

The ref prop is required and must point to an HTMLElement .
In development, an error is logged if ref is missing or invalid.

State Updates & Event Handling

The hook listens to the mousemove event on the document.
State is only updated if any value changes, for performance.
If trackOutside is false , state only updates when the mouse is inside the element; if true , updates everywhere.
If clampToZero is true , elX and elY are clamped to zero or greater.

Returned Data

The hook returns an object with mouse position in the document, relative to the element, and element dimensions.

Cleanup

The event listener is removed automatically when the component unmounts.

Caveats & Best Practices

The hook is intended for use in the browser; on the server, it will always return zeros.
Ensure the ref is stable and points to a visible element.
If the element is not in the DOM, all values will be zero.
For best performance, avoid unnecessary re-renders by memoizing the ref.

Files in this hook

Source	Destination
files/use-mouse.ts	src/hooks/use-mouse.ts