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.

Install

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!

import React from 'react'
import { MouseTrackerProvider } from '@devdogukan/mouse-tracker'

const App = () => {
  return (
    <MouseTrackerProvider>
      <MouseTrackerProvider.Tracker />
      {/* Your components and content */}
    </MouseTrackerProvider>
  )
}

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:

import { useMouseTracker } from '@devdogukan/mouse-tracker'
import React, { useRef } from 'react'

const CustomTracker = () => {
  const ref = useRef<HTMLDivElement | null>(null)

  useMouseTracker(ref)

  return (
    <div
      className='tracker-wrapper'
      style={{
        position: 'fixed',
        top: '0',
        left: '0',
        pointerEvents: 'none'
      }}
      ref={ref}
    >
      {/* Your custom tracker content */}
    </div>
  )
}

export default CustomTracker

• Change default Tracker inside to MouseTrackerProvider and remove <MouseTrackerProvider.Tracker/>

HOOKS

useIntersectionElement

Mouse Tracker provides a custom hook, useIntersectionElement, for tracking mouse intersection with an element.

USAGE

import { useIntersectionElement } from '@devdogukan/mouse-tracker'
import React, { useRef } from 'react'

const Tracker = () => {
  const trackedElementRef = useRef<HTMLDivElement | null>(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 <div ref={trackedElementRef}>{/* Your component content */}</div>
}

export default Tracker

API

| Parameter | Type | Description | | ---------- | ----------------------------- | --------------------------------------------------------- | | ref | RefObject<HTMLElement> | 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

import { useMouseTracker } from '@devdogukan/mouse-tracker'
import React, { useRef } from 'react'

const Tracker = () => {
  const ref = useRef<HTMLDivElement | null>(null)

  useMouseTracker(ref)

  return (
    <div className='tracker-wrapper' ref={ref}>
      <div className='tracker-dot-container'>
        <div className='circle-dot tracker-dot'></div>
      </div>
    </div>
  )
}

export default Tracker

API

| Parameter | Type | Description | | --------- | ------------------------ | --------------------------------------- | | ref | RefObject<HTMLElement> | Reference to the element to be tracked. |

useTrackerContext

useTrackerContext is a custom hook that provides access to the mouse tracker context value.

USAGE

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<HTMLElement>): A reference to the element to be tracked.
• setTrackerRef (Dispatch<SetStateAction<RefObject<HTMLElement>>>): A function to set the reference to the tracked element.

License

MIT © devepdogukan