---
title: useMouse
description: "Tracks the mouse/pointer cursor position reactively. Supports multiple coordinate systems (`page`, `client`, `screen`, `movement`) and optional touch event tracking."
category: Sensors
sidebar:
  order: 2
type-table:
  import: "@usels/web"
  name: "UseMouse"
  params:
    children:
      - UseMouseOptions
---

## Demo

## Usage

<CodeTabs>
  <Fragment slot="hook">
    ```tsx twoslash
    // @noErrors
    import { useMouse } from "@usels/web";

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

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

  </Fragment>
  <Fragment slot="scope">
    ```tsx
    import { createMouse } from "@usels/web";

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

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

  </Fragment>
</CodeTabs>

### Coordinate types

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

```tsx
// @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.

```tsx
// @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.

```tsx
// @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.

```tsx
// @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>
  );
}
```