# usePointerPosition

Where the mouse, pen, or finger is over an element, in pixels from its top-left corner, or `null` while it's outside (and on the server). Attach the returned ref to the element.

With a mouse it follows hovering; with a finger, only while it touches, and it turns `null` when the finger lifts. Re-renders on every move, so keep the component small, or skip React for pure visuals (see below).

## Import

```ts
import { usePointerPosition } from '@vincent.ri/react-tils'
// or only this hook
import { usePointerPosition } from '@vincent.ri/react-tils/usePointerPosition'
```

## Usage

```ts
const [ref, pointer] = usePointerPosition<HTMLDivElement>()
return (
  <div
    ref={ref}
    className="card"
    style={{ '--x': `${pointer?.x ?? -999}px`, '--y': `${pointer?.y ?? -999}px` } as CSSProperties}
  />
)
// .card { background: radial-gradient(200px at var(--x) var(--y), #fff3, transparent) }
```

## When to use it

A spotlight or glow that follows the cursor on a card, a tooltip or magnifier at the pointer, crosshairs on a chart, or a hover preview that depends on the position (scrubbing a video thumbnail).

## When not to

Plain hover styling (CSS `:hover`); a drag (`useDrag`); or a page-wide custom cursor, which re-renders the whole app per move: use `useEventListener('window', 'pointermove', …)` and set a CSS variable or `transform` on the element directly.

## API

```ts
function usePointerPosition<T extends Element = HTMLElement>(): [(element: T | null) => void, PointerPosition | null]
```

**Returns** `[ref, position]`: `position` is `{ x, y }`, or `null` while the pointer is outside.

### Types

```ts
export type PointerPosition = {
  /** Pixels from the element's left edge. */
  x: number;
  /** Pixels from the element's top edge. */
  y: number;
};
```

## Browser support

Works in all modern browsers.

## Coming from another library?

Other libraries call this `useMouse` (react-use), `useMousePosition`, `usePointer`.

---

198 B minified and brotlied
Source: https://github.com/vincentri/react-tils/blob/main/src/usePointerPosition.ts
Docs page: https://vincentri.github.io/react-tils/hooks/usePointerPosition/
Previous: [useDrag](https://vincentri.github.io/react-tils/hooks/useDrag.md)
Next: [useFileDrop](https://vincentri.github.io/react-tils/hooks/useFileDrop.md)