@leejaehyeok/use-intersection-observer

English | 한국어

React hooks for observing element visibility using the Intersection Observer API. Provides two hooks: useIntersectionObserver for tracking a single element and useIntersectionObserverGroup for tracking multiple elements. Perfect for lazy loading, infinite scroll, analytics tracking, and scroll-based animations.

📦 Installation

npm install @leejaehyeok/use-intersection-observer

🚀 Quick Start

Single Element Tracking

Track the visibility of a single element:

import React, { useRef } from "react";
import { useIntersectionObserver } from "@leejaehyeok/use-intersection-observer";

export function MyComponent() {
  const { setContainerRef, isVisible, hasEntered, target } = useIntersectionObserver({
    targetSelector: "[data-target]",
    onEntered: (entry) => console.log("Entered!"),
    onExited: (entry) => console.log("Exited!"),
  });

  return (
    <div ref={setContainerRef}>
      <div data-target>{isVisible ? "Visible" : "Hidden"}</div>
      <button onClick={() => target?.scrollIntoView({ behavior: "smooth" })} disabled={!target}>
        Scroll to target
      </button>
    </div>
  );
}

Multiple Elements Tracking

Track visibility of multiple elements:

import React from "react";
import { useIntersectionObserverGroup } from "@leejaehyeok/use-intersection-observer";

export function MyComponent() {
  const { setContainerRef, states } = useIntersectionObserverGroup({
    keyAttribute: "data-key",
    onEntered: (key, entry) => console.log(`Item ${key} entered`),
  });

  return (
    <div ref={setContainerRef}>
      {["item-1", "item-2", "item-3"].map((key) => (
        <div key={key} data-key={key}>
          {states[key]?.isVisible ? "In view" : "Out of view"}
        </div>
      ))}
    </div>
  );
}

🧠 Key Features

• Single & Multiple Elements: Track one or many elements with dedicated hooks.
• Lifecycle Callbacks: onEntered, onExited, and onChange callbacks for full control.
• State Tracking: Know if elements are visible or have been entered.
• Target Element Access: Get a direct reference to the observed DOM element via target.
• Once Option: Auto-unobserve after first intersection with once: true.
• Flexible Root: Use the viewport or a scrollable container as the intersection root.
• Reset Control: Reset observation state programmatically with reset() method.

🔗 Links

• GitHub Repository
• Package Source Code
• Issue Tracker

📄 License

MIT © leejh1316