# @react-hook/mouse-position

> A React hook for tracking the position, hover, and down state of the mouse as it interacts with an element with interop between touch and mouse devices.

Latest version **4.1.3** (published 2021-10-27) · MIT license · 0 weekly downloads

## Install

```sh
npm install @react-hook/mouse-position
pnpm add @react-hook/mouse-position
yarn add @react-hook/mouse-position
bun add @react-hook/mouse-position
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.1.3 |
| Published | 2021-10-27 |
| First published | 2019-04-06 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 130.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1530 |
| Author | Jared Lunde |
| Maintainers | jaredlunde |
| Keywords | react, react hook, hook, react hooks, hooks, mousemove, mouse position, mouse tracker, use mouse position, usemouseposition, mouse position hook, react mouse position hook |

## Links

- npm: https://www.npmjs.com/package/@react-hook/mouse-position
- Repository: https://github.com/jaredLunde/react-hook
- Homepage: https://github.com/jaredLunde/react-hook/tree/master/packages/mouse-position#readme
- Issues: https://github.com/jaredLunde/react-hook/issues
- npm.io page: https://npm.io/package/@react-hook/mouse-position

## Dependencies (2)

- [@react-hook/event](https://npm.io/package/@react-hook/event.md) ^1.2.6
- [@react-hook/throttle](https://npm.io/package/@react-hook/throttle.md) ^2.2.0

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 4.1.3 (latest) — 2021-10-27
- 4.1.2 — 2021-10-27
- 4.1.1 — 2021-09-10
- 4.1.0 — 2020-06-07
- 4.0.0 — 2020-05-28
- 3.2.2 — 2020-04-24
- 3.2.1 — 2020-04-23
- 3.2.0 — 2020-04-22
- 3.1.0 — 2020-03-24
- 3.0.4 — 2020-01-29
- 3.0.3 — 2020-01-25
- 3.0.2 — 2020-01-25
- 3.0.1 — 2019-12-29
- 3.0.0 — 2019-12-29
- 2.0.5 — 2019-12-25
- … 9 more at https://npm.io/package/@react-hook/mouse-position/versions

## README

<hr>
<div align="center">
  <h1 align="center">
    useMouse()
  </h1>
</div>

<p align="center">
  <a href="https://bundlephobia.com/result?p=@react-hook/mouse-position">
    <img alt="Bundlephobia" src="https://img.shields.io/bundlephobia/minzip/@react-hook/mouse-position?style=for-the-badge&labelColor=24292e">
  </a>
  <a aria-label="Types" href="https://www.npmjs.com/package/@react-hook/mouse-position">
    <img alt="Types" src="https://img.shields.io/npm/types/@react-hook/mouse-position?style=for-the-badge&labelColor=24292e">
  </a>
  <a aria-label="Build status" href="https://travis-ci.com/jaredLunde/react-hook">
    <img alt="Build status" src="https://img.shields.io/travis/com/jaredLunde/react-hook?style=for-the-badge&labelColor=24292e">
  </a>
  <a aria-label="NPM version" href="https://www.npmjs.com/package/@react-hook/mouse-position">
    <img alt="NPM Version" src="https://img.shields.io/npm/v/@react-hook/mouse-position?style=for-the-badge&labelColor=24292e">
  </a>
  <a aria-label="License" href="https://jaredlunde.mit-license.org/">
    <img alt="MIT License" src="https://img.shields.io/npm/l/@react-hook/mouse-position?style=for-the-badge&labelColor=24292e">
  </a>
</p>

<pre align="center">npm i @react-hook/mouse-position</pre>
<hr>

A React hook for tracking the position, hover, and "down" state of the mouse as it interacts
with an element. This hook provides interoperability between touch and desktop devices and will treat
`ontouch` events the same as `onmouse` ones. Additionally, this hook is throttled to `30fps` by default
using a [useThrottle() hook](https://github.com/jaredLunde/react-hook/tree/master/packages/throttle),
though the precise frame rate is configurable.

## Quick Start

[Check out the example on **CodeSandbox**](https://codesandbox.io/s/react-hookmouse-position-example-udsxi?file=/src/App.js)

```jsx harmony
import * as React from 'react'
import useMouse from '@react-hook/mouse-position'

const Component = (props) => {
  const ref = React.useRef(null)
  const mouse = useMouse(ref, {
    enterDelay: 100,
    leaveDelay: 100,
  })

  return (
    // You must provide the ref to the element you're tracking the
    // mouse position of
    <div ref={ref}>
      Hover me and see where I am relative to the element:
      <br />
      x: ${mouse.x}
      y: ${mouse.y}
    </div>
  )
}
```

## API

### useMouse(target, options?)

A hook for tracking the mouse position in an element with interoperability between touch
devices and mouse devices.

#### Arguments

| Argument | Type                                                       | Required? | Description                                                            |
| -------- | ---------------------------------------------------------- | --------- | ---------------------------------------------------------------------- |
| target   | <code>React.RefObject&lt;T&gt; &#124; T &#124; null</code> | Yes       | The React ref, `window`, or HTML element to add the event listener to  |
| options  | [`UseMouseOptions`](#usemouseoptions)                      | No        | Configuration options. See [`UseMouseOptions`](#usemouseoptions) below |

#### Returns [`MousePosition`](#mouseposition)

The mouse position data for the target element. See [`MousePosition`](#mouseposition) below.

#### UseMouseOptions

| Property   | Type     | Default | Description                                                                                            |
| ---------- | -------- | ------- | ------------------------------------------------------------------------------------------------------ |
| enterDelay | `number` | `0`     | The time in `ms` to wait after an initial action before setting the latest `mousemove` events to state |
| leaveDelay | `number` | `0`     | The time in `ms` to wait after a final action before setting the latest `mouseleave` events to state   |
| fps        | `number` | `30`    | The rate in frames-per-second that the mouse position should update                                    |

#### MousePosition

| Key           | Type      | Default | Description                                                                                       |
| ------------- | --------- | ------- | ------------------------------------------------------------------------------------------------- |
| x             | `number`  | `null`  | Mouse position relative to the left edge of the element, `null` if mouse is not over the element  |
| y             | `number`  | `null`  | Mouse position relative to the top edge of the element, `null` if mouse is not over the element   |
| pageX         | `number`  | `null`  | Mouse position relative to the left edge of the document, `null` if mouse is not over the element |
| pageY         | `number`  | `null`  | Mouse position relative to the top edge of the document, `null` if mouse is not over the element  |
| clientX       | `number`  | `null`  | Mouse position relative to the left edge of the client, `null` if mouse is not over the element   |
| clientY       | `number`  | `null`  | Mouse position relative to the top edge of the client, `null` if mouse is not over the element    |
| screenX       | `number`  | `null`  | Mouse position relative to the left edge of the screen, `null` if mouse is not over the element   |
| screenY       | `number`  | `null`  | Mouse position relative to the top edge of the screen, `null` if mouse is not over the element    |
| elementWidth  | `number`  | `null`  | `DOMRect.width` of the element, `null` if mouse is not over the element                           |
| elementHeight | `number`  | `null`  | `DOMRect.height` of the element, `null` if mouse is not over the element                          |
| isOver        | `boolean` | `false` | `true` if the mouse is currently hovering over the element                                        |
| isDown        | `boolean` | `false` | `true` if the mouse is currently hovering over the element AND is down                            |
| isTouch       | `boolean` | `false` | `true` if the the last event was triggered by a touch event                                       |

## LICENSE

MIT

---
_Source: https://npm.io/package/@react-hook/mouse-position · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._