https://github.com/devepdogukan/mouse-tracker
Lightweight React library for mouse interaction tracking. Monitor positions, visibility, and trigger custom actions effortlessly. Elevate your user experiences with ease.
https://github.com/devepdogukan/mouse-tracker
javascript mouse-events mouse-tracker react react-hooks reactcomponents reactjs web webdevelopment
Last synced: 4 months ago
JSON representation
Lightweight React library for mouse interaction tracking. Monitor positions, visibility, and trigger custom actions effortlessly. Elevate your user experiences with ease.
- Host: GitHub
- URL: https://github.com/devepdogukan/mouse-tracker
- Owner: devepdogukan
- Created: 2024-02-01T18:32:43.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-02-04T08:51:18.000Z (almost 2 years ago)
- Last Synced: 2025-08-05T09:13:12.407Z (5 months ago)
- Topics: javascript, mouse-events, mouse-tracker, react, react-hooks, reactcomponents, reactjs, web, webdevelopment
- Language: TypeScript
- Homepage:
- Size: 313 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# mouse-tracker
Mouse Tracker is a lightweight React library that provides components and hooks for easy mouse interaction tracking within your applications. With Mouse Tracker, you can effortlessly monitor mouse positions, visibility, and trigger specific actions based on user interactions. Enhance your user experience by incorporating precise mouse tracking capabilities into your React components.
[](https://www.npmjs.com/package/@devdogukan/mouse-tracker) [](https://standardjs.com) [](https://github.com/devepdogukan/mouse-tracker)
## Install
```bash
npm install @devdogukan/mouse-tracker
```
## Usage
- Wrap your `App` component with `MouseTrackerProvider`.
- If you want to use the default tracker, simply include `MouseTrackerProvider.Tracker`.
- That's it!
```tsx
import React from 'react'
import { MouseTrackerProvider } from '@devdogukan/mouse-tracker'
const App = () => {
return (
{/* Your components and content */}
)
}
```
## Custom Tracker
To create a custom tracker, follow these steps:
1. Import the `useMouseTracker` hook from `@devdogukan/mouse-tracker`.
2. Create a functional component for your custom tracker.
3. Use the `useMouseTracker` hook on a DOM element within your custom tracker component.
4. Apply the necessary CSS styles for the custom tracker, ensuring it has `position: fixed;`, `top: 0;`, `left: 0;`, and `pointer-events: none;`.
Here's an example of a custom tracker component:
```tsx
import { useMouseTracker } from '@devdogukan/mouse-tracker'
import React, { useRef } from 'react'
const CustomTracker = () => {
const ref = useRef(null)
useMouseTracker(ref)
return (
{/* Your custom tracker content */}
)
}
export default CustomTracker
```
- Change default Tracker inside to MouseTrackerProvider and remove
# HOOKS
## useIntersectionElement
Mouse Tracker provides a custom hook, useIntersectionElement, for tracking mouse intersection with an element.
### USAGE
```tsx
import { useIntersectionElement } from '@devdogukan/mouse-tracker'
import React, { useRef } from 'react'
const Tracker = () => {
const trackedElementRef = useRef(null)
useIntersectionElement({
ref: trackedElementRef,
options: {
keepInside: true // Keep cloned element inside the tracked element
},
callback: ({ isIntersection, trackRef, event }) => {
// Handle mouse intersection events
console.log('Mouse is inside:', isIntersection)
console.log('Tracked element reference:', trackRef)
console.log('Mouse event details:', event)
}
})
return
{/* Your component content */}
}
export default Tracker
```
### API
| Parameter | Type | Description |
| ---------- | ----------------------------- | --------------------------------------------------------- |
| `ref` | `RefObject` | Reference to the element to be tracked. |
| `options` | `IntersectionElementOptions` | Optional configuration for the intersection behavior. |
| `callback` | `IntersectionElementCallback` | Callback function triggered on mouse intersection events. |
#### IntersectionElementOptions
| Option | Type | Default | Description |
| ------------ | --------- | ------- | --------------------------------------------------- |
| `keepInside` | `boolean` | `false` | Keep the cloned element inside the tracked element. |
#### IntersectionElementCallback
| Parameter | Type | Description |
| ---------------- | ------------- | ------------------------------------------- |
| `isIntersection` | `boolean` | Indicates whether the mouse is inside. |
| `trackRef` | `HTMLElement` | Reference to the tracked or cloned element. |
| `event` | `MouseEvent` | Mouse event details. |
## useMouseTracker
`useMouseTracker` is a custom React hook that enables tracking the mouse position and visibility for a specified HTML element.
### USAGE
```tsx
import { useMouseTracker } from '@devdogukan/mouse-tracker'
import React, { useRef } from 'react'
const Tracker = () => {
const ref = useRef(null)
useMouseTracker(ref)
return (
)
}
export default Tracker
```
### API
| Parameter | Type | Description |
| --------- | ------------------------ | --------------------------------------- |
| `ref` | `RefObject` | Reference to the element to be tracked. |
## useTrackerContext
`useTrackerContext` is a custom hook that provides access to the mouse tracker context value.
### USAGE
```tsx
import { useTrackerContext } from '@devdogukan/mouse-tracker'
import React, { useRef } from 'react'
const MyComponent = () => {
const context = useTrackerContext();
// Access context properties such as trackerRef and setTrackerRef
return (
// Your component content
);
}
export default Tracker
```
### Returns
The `useTrackerContext` hook returns an object with the following properties:
- `trackerRef` (`RefObject`): A reference to the element to be tracked.
- `setTrackerRef` (`Dispatch>>`): A function to set the reference to the tracked element.
## License
MIT © [devepdogukan](https://github.com/devepdogukan)