useMouse

Tracks the mouse/pointer cursor position reactively. Supports multiple coordinate systems (page, client, screen, movement) and optional touch event tracking.

Demo

useMouse

Track mouse cursor position in real-time.

Coordinate Typepageclientscreenmovement

X

0px

Y

0px

Source: none

move your mouse here

Usage

Hook

import { useMouse } from "@usels/web";

function Component() {
  const { x$, y$, sourceType$ } = useMouse();

  return (
    <div>
      {x$.get()}, {y$.get()} — {sourceType$.get()}
    </div>
  );
}

Scope

import { createMouse } from "@usels/web";

function Component() {
  "use scope"
  const { x$, y$, sourceType$ } = createMouse();

  return (
    <div>
      {x$.get()}, {y$.get()} — {sourceType$.get()}
    </div>
  );
}

Coordinate types

The type option selects which coordinate system to use. It is read only at mount time.

// @noErrors
import { useMouse } from "@usels/web";
// ---cut---
// "page" (default) — relative to the document
const { x$, y$ } = useMouse({ type: "page" });

// "client" — relative to the viewport
const { x$: cx$, y$: cy$ } = useMouse({ type: "client" });

// "screen" — relative to the screen
const { x$: sx$, y$: sy$ } = useMouse({ type: "screen" });

// "movement" — delta movement since last event (MouseEvent.movementX/Y)
const { x$: mx$, y$: my$ } = useMouse({ type: "movement" });

Touch support

Touch tracking is enabled by default. Use touch: false to disable it, or resetOnTouchEnds: true to reset coordinates back to the initial value when the finger lifts.

// @noErrors
import { useMouse } from "@usels/web";
// ---cut---
// Disable touch tracking
const { x$, y$ } = useMouse({ touch: false });

// Reset to origin on touchend
const { x$: rx$, y$: ry$ } = useMouse({ resetOnTouchEnds: true });

Custom target

By default events are listened on window. Pass any element (or an Observable wrapping one) via target to scope tracking to that element.

// @noErrors
import { useRef$ } from "@usels/core";
import { useMouse } from "@usels/web";

function Component() {
  const el$ = useRef$<HTMLDivElement>();
  const { x$, y$ } = useMouse({ target: el$ });

  return (
    <div ref={el$}>
      {x$.get()}, {y$.get()}
    </div>
  );
}

With useMouseInElement combination

Use useMouse for global coordinates while useMouseInElement provides element-relative coordinates at the same time.

// @noErrors
import { useRef$ } from "@usels/core";
import { useMouse, useMouseInElement } from "@usels/web";

function Component() {
  const el$ = useRef$<HTMLDivElement>();
  const { x$, y$ } = useMouse();
  const { elementX$, elementY$, isOutside$ } = useMouseInElement(el$);

  return (
    <div ref={el$}>
      Global: {x$.get()}, {y$.get()}
      <br />
      Local: {elementX$.get()}, {elementY$.get()} (outside: {String(isOutside$.get())})
    </div>
  );
}

Type

Parameters

Parameter	Type	Description
options	UseMouseOptions (optional)	-

UseMouseOptions

Option	Type	Default	Description
type	UseMouseCoordType	-	Coordinate type. Default: “page”
touch	boolean	-	Track touch events. Default: true
resetOnTouchEnds	boolean	-	Reset coordinates on touchend. Default: false
target	MaybeEventTarget	-	Event target. Default: window
initialValue	{ x: number; y: number; }	-	Initial coordinate values. Default: { x: 0, y: 0 }
eventFilter	EventFilter<any[], any, void>	-	-
window	WindowSource	-	-

Returns

UseMouseReturn

Name	Type	Description
x$	ReadonlyObservable<number>	X coordinate
y$	ReadonlyObservable<number>	Y coordinate
sourceType$	ReadonlyObservable<UseMouseSourceType>	Event source type: “mouse” | “touch” | null

Source

View on GitHub