react-inter-event

A lightweight React hook library that makes it easy to implement intersection events (scroll visibility, element tracking) and interactive events such as mouse tracking.

It provides simple, reusable hooks to detect when elements are visible in the viewport, track mouse position and clicks, and respond to other upcoming interactive events like keyboard and gestures.

✨ Features

• 📦 Minimal, dependency-free (only React as peer dependency)
• 🌳 Tree-shakeable – only include the parts you import
• 👀 Detect element visibility with IntersectionObserver
• 🖱 Extensible – includes useMouse for mouse tracking
• ⌨️ Future: keyboard and gesture hooks

🚀 Installation

npm install react-inter-event
# or
yarn add react-inter-event

🔧 Usage

Intersection Observer (Scroll tracker)

The IntersectionObserver is a browser API that allows you to observe how much of a DOM element is visible in the viewport or within a parent container.

Example: Trigger animations when elements appear on screen while scrolling

Key features: Configurable threshold -> control how much visibility triggers events Supports infinite observation or one-time triggers

import React, { useRef } from "react";
import useIntersectionObserver from "react-inter-event";

function Example() {
  const targetRef = useRef(null);

  const { isVisible, destination } = useIntersectionObserver({
    elementRef: targetRef,
    sensitive: true,
    infinite: false,
  });

  return (
    <div style={{ height: "150vh" }}>
      <div
        ref={targetRef}
        style={{
          height: 200,
          background: isVisible ? "lightgreen" : "lightcoral",
        }}
      >
        {isVisible
          ? `Visible (ratio: ${destination})`
          : "Scroll down to reveal me"}
      </div>
    </div>
  );
}

Mouse Tracker

The Mouse Tracker hook tracks the user’s mouse position and click state in real-time.

Example: Cursor-based interactions, hover effects, or game controls

Key features: Based on standard browser mouse events (mousemove, mousedown, mouseup) Optional click state duration (clickDuration) Disabled on mobile devices (no touch events)

import React from "react";
import { useMouseTracker } from "react-inter-event";

function MouseExample() {
  const { mousePosition, isClicked } = useMouseTracker({ clickDuration: 1000 });

  return (
    <div
      style={{
          position: "fixed",
          left: mousePosition.x,
          top: mousePosition.y,
          width: isClicked ? "10px" : "100px",
          height: isClicked ? "10px" : "100px",
          pointerEvents: "none",
          background: "#8386dd10",
          borderRadius: "50%",
          transform: "translate(-50%, -50%)",
          transition: "width .3s, height .3s",
      }}
    >
    </div>
  );
}

📖 API

useIntersectionObserver(options)

Options:

• elementRef (ref, required) – The target element reference.
• option (object, optional) – IntersectionObserver options: option: { threshold (number[], default [0, 0.1, ..., 1]) – Visibility thresholds. root (Element | null, default null) – The container to use as viewport. rootMargin (string, default "0px") – Margin around the root. }
• sensitive (boolean, default false) – If true, returns intersection ratio (destination).
• infinite (boolean, default false) – If false, stops observing after first trigger.

Returns:

{
  isVisible: boolean;     // true if element is visible in viewport
  destination: number;    // intersection ratio (0–1) or 1 if fully visible
}

useMouseTracker(options)

Options:

• clickDuration (number, optional) - Time in milliseconds to keep isClicked true after mouse down. Default is 0.

Returns:

{
  mousePosition: { x: number, y: number };  // Current mouse coordinates
  isClicked: boolean;                       // True if mouse is pressed
}

🛠 Examples

Infinite Intersection Observer Example

• isVisible

  const elementRef = useRef(null);
  const { isVisible } = useIntersectionObserver({
    elementRef,
    infinite: true
  });

  return (
    <div
      style={{
        opacity: isVisible ? 1 : 0,
        transition: "opacity 1s ease-in-out",
      }}
      ref={elementRef}
    >
      ...
    </div>
  );

• Destination

  const elementRef = useRef(null);
  const { destination } = useIntersectionObserver({
    elementRef,
    sensitive: true,
  });

  return (
    <div
      style={{
        opacity: destination,
      }}
      ref={elementRef}
    >
      ...
    </div>
  );

useMouseTracker Example

import React from "react";
import { useMouseTracker } from "react-inter-event";

function MouseExample() {

  const { mousePosition, isClicked } = useMouseTracker({ clickDuration: 1000 });

  return (
    <div
      style={{
          position: "fixed",
          left: mousePosition.x,
          top: mousePosition.y,
          width: isClicked ? "10px" : "100px",
          height: isClicked ? "10px" : "100px",
          pointerEvents: "none",
          background: "#8386dd10",
          borderRadius: "50%",
          transform: "translate(-50%, -50%)",
          transition: "width .3s, height .3s",
      }}
    >
    </div>
  );
}

TypeScript Types

Intersection Observer Type

interface UseObserverOption {
  threshold?: number | number[];        // Visibility thresholds
  root?: Element | Document | null;     // The viewport or container
  rootMargin?: string;                  // Margin around the root
}

interface UseObserverParams {
  elementRef: RefObject<Element>;       // Target element reference
  option?: UseObserverOption;           // IntersectionObserver options
  sensitive?: boolean;                  // Return intersection ratio if true
  infinite?: boolean;                   // Continue observing infinitely if true
}

interface UseObserverReturn {
  isVisible: boolean;                   // True if element is visible in viewport
  destination: number;                  // Intersection ratio (0–1)
}

Mouse Tracker Type

export interface MousePosition {
  x: number;    // Current mouse X coordinate
  y: number;    // Current mouse Y coordinate
}

export interface UseMouseOptions {
  clickDuration?: number; // Time in milliseconds to keep isClicked true after mouse down
}

export interface UseMouseReturn {
  mousePosition: MousePosition; // Current mouse coordinates
  isClicked: boolean;           // True if mouse is currently pressed
}

This way the API section is clean Markdown, readable in GitHub or npm pages.

If you want, I can also tweak the “Examples” section to show a mouse tracking example, so it aligns with your planned future features. Do you want me to do that?