@leejaehyeok/use-intersection-observer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lee Jae Hyeok
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+# @leejaehyeok/use-intersection-observer
+
+[English](./README.md) | [한국어](./README-ko.md)
+
+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
+
+```bash
+npm install @leejaehyeok/use-intersection-observer
+```
+
+## 🚀 Quick Start
+
+### Single Element Tracking
+
+Track the visibility of a single element:
+
+```tsx
+import React, { useRef } from "react";
+import { useIntersectionObserver } from "@leejaehyeok/use-intersection-observer";
+
+export function MyComponent() {
+  const { setContainerRef, isVisible, hasEntered } = 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>
+    </div>
+  );
+}
+```
+
+### Multiple Elements Tracking
+
+Track visibility of multiple elements:
+
+```tsx
+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.
+- **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](https://github.com/leejh1316/react-hooks)
+- [Package Source Code](https://github.com/leejh1316/react-hooks/tree/master/packages/use-intersection-observer)
+- [Issue Tracker](https://github.com/leejh1316/react-hooks/issues)
+
+## 📄 License
+
+MIT © [leejh1316](https://github.com/leejh1316)

package/dist/index.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require(`react`);function t(t){let n=(0,e.useRef)(t);return(0,e.useLayoutEffect)(()=>{n.current=t},[t]),n}function n(n){let{root:r=null,once:i=!1,targetSelector:a=`[data-intersection-target]`,onEntered:o,onExited:s,onChange:c,...l}=n||{},[u,d]=(0,e.useState)(()=>({isVisible:!1,hasEntered:!1})),f=(0,e.useRef)(i),p=(0,e.useRef)(r),m=(0,e.useRef)(null),h=(0,e.useRef)(null),g=(0,e.useRef)(null),_=(0,e.useRef)(!1),v=t(o),y=t(s),b=t(c),x=(0,e.useCallback)(()=>{g.current?.disconnect()},[]),S=(0,e.useCallback)(()=>{if(!h.current||!m.current){console.warn(`[use-intersection-observer] 관찰할 요소가 없습니다. reset이 실패했습니다.`);return}g.current?.unobserve(m.current),_.current=!1,d(()=>({isVisible:!1,hasEntered:!1})),g.current?.observe(m.current)},[]),C=(0,e.useCallback)((e,t)=>{let n=e[0],r=n.isIntersecting;m.current=n.target,b.current?.(r?`enter`:`exit`,n,t),r?(_.current||=f.current,v.current?.(n,t),d(()=>({isVisible:r,hasEntered:!0}))):(y.current?.(n,t),d(e=>({...e,isVisible:r})),_.current&&t.unobserve(n.target))},[]);return{setContainerRef:(0,e.useCallback)(e=>{if(!e){h.current=null,x();return}h.current=e;let t=p.current===`container`?e:null,n=e.querySelectorAll(a),r=n.length>0?n:e.firstElementChild;if(!r){console.warn(`[use-intersection-observer] 대상을 찾을 수 없습니다: "${a}"`);return}r instanceof NodeList&&r.length>1&&console.warn(`여러 개의 요소가 발견되었습니다. 첫 번째 요소만 추적합니다.`);let i=new IntersectionObserver(C,{...l,root:t}),o=r instanceof NodeList?r[0]:r;g.current=i,i.observe(o)},[C]),reset:S,...u}}function r(n){let{root:r=null,once:i=!1,keyAttribute:a=`data-intersection-key`,onEntered:o,onExited:s,onChange:c,...l}=n||{},[u,d]=(0,e.useState)(()=>({})),f=(0,e.useRef)(i),p=(0,e.useRef)(r),m=(0,e.useRef)(null),h=(0,e.useRef)(null),g=(0,e.useRef)(null),_=(0,e.useRef)({}),v=t(o),y=t(s),b=t(c),x=(0,e.useCallback)(()=>{h.current?.disconnect(),g.current?.disconnect()},[]),S=(0,e.useCallback)(e=>{if(!m.current){console.warn(`[use-intersection-observer-group] 컨테이너가 없습니다. reset이 실패했습니다.`);return}if(e){let t=m.current.querySelector(`[${a}="${e}"]`);t instanceof Element&&(h.current?.unobserve(t),_.current[e]=!1,d(t=>({...t,[e]:{isVisible:!1,hasEntered:!1}})),h.current?.observe(t))}else{h.current?.disconnect(),_.current={},d(()=>({}));let e=m.current.querySelectorAll(`[${a}]`),t=p.current===`container`?m.current:null,n=new IntersectionObserver(w,{...l,root:t});h.current=n,e.forEach(e=>{n.observe(e)})}},[]),C=(0,e.useCallback)(e=>{e.forEach(e=>{e.addedNodes.forEach(e=>{e instanceof Element&&[...e.hasAttribute(a)?[e]:[],...Array.from(e.querySelectorAll(`[${a}]`))].forEach(e=>{h.current?.observe(e)})}),e.removedNodes.forEach(e=>{e instanceof Element&&[...e.hasAttribute(a)?[e]:[],...Array.from(e.querySelectorAll(`[${a}]`))].forEach(e=>{let t=e.getAttribute(a);t&&(h.current?.unobserve(e),delete _.current[t],d(e=>{let n={...e};return delete n[t],n}))})})})},[]),w=(0,e.useCallback)((e,t)=>{d(n=>{let r={...n};return e.forEach(e=>{let i=e.target.getAttribute(a);if(!i){console.warn(`[use-intersection-observer-group] ${a} 속성이 없습니다.`);return}let o=e.isIntersecting,s=n[i];b.current?.(i,o?`enter`:`exit`,e,t),o?(_.current[i]||=f.current,v.current?.(i,e,t),r[i]={isVisible:o,hasEntered:!0}):(y.current?.(i,e,t),r[i]={isVisible:o,hasEntered:s?.hasEntered??!1},_.current[i]&&t.unobserve(e.target))}),r})},[]);return{setContainerRef:(0,e.useCallback)(e=>{if(!e){m.current=null,x();return}m.current=e;let t=p.current===`container`?e:null,n=e.querySelectorAll(`[${a}]`),r=new IntersectionObserver(w,{...l,root:t});h.current=r;let i=new MutationObserver(C);i.observe(e,{childList:!0,subtree:!0}),g.current=i,n.length!==0&&n.forEach(e=>{r.observe(e)})},[w]),reset:S,states:u}}exports.useIntersectionObserver=n,exports.useIntersectionObserverGroup=r;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './useIntersectionObserver';
+export * from './useIntersectionObserverGroup';

package/dist/index.js

@@ -0,0 +1,149 @@
+import { useCallback as e, useLayoutEffect as t, useRef as n, useState as r } from "react";
+//#region ../use-latest-ref/dist/index.js
+function i(e) {
+	let r = n(e);
+	return t(() => {
+		r.current = e;
+	}, [e]), r;
+}
+//#endregion
+//#region src/useIntersectionObserver.ts
+function a(t) {
+	let { root: a = null, once: o = !1, targetSelector: s = "[data-intersection-target]", onEntered: c, onExited: l, onChange: u, ...d } = t || {}, [f, p] = r(() => ({
+		isVisible: !1,
+		hasEntered: !1
+	})), m = n(o), h = n(a), g = n(null), _ = n(null), v = n(null), y = n(!1), b = i(c), x = i(l), S = i(u), C = e(() => {
+		v.current?.disconnect();
+	}, []), w = e(() => {
+		if (!_.current || !g.current) {
+			console.warn("[use-intersection-observer] 관찰할 요소가 없습니다. reset이 실패했습니다.");
+			return;
+		}
+		v.current?.unobserve(g.current), y.current = !1, p(() => ({
+			isVisible: !1,
+			hasEntered: !1
+		})), v.current?.observe(g.current);
+	}, []), T = e((e, t) => {
+		let n = e[0], r = n.isIntersecting;
+		g.current = n.target, S.current?.(r ? "enter" : "exit", n, t), r ? (y.current ||= m.current, b.current?.(n, t), p(() => ({
+			isVisible: r,
+			hasEntered: !0
+		}))) : (x.current?.(n, t), p((e) => ({
+			...e,
+			isVisible: r
+		})), y.current && t.unobserve(n.target));
+	}, []);
+	return {
+		setContainerRef: e((e) => {
+			if (!e) {
+				_.current = null, C();
+				return;
+			}
+			_.current = e;
+			let t = h.current === "container" ? e : null, n = e.querySelectorAll(s), r = n.length > 0 ? n : e.firstElementChild;
+			if (!r) {
+				console.warn(`[use-intersection-observer] 대상을 찾을 수 없습니다: "${s}"`);
+				return;
+			}
+			r instanceof NodeList && r.length > 1 && console.warn("여러 개의 요소가 발견되었습니다. 첫 번째 요소만 추적합니다.");
+			let i = new IntersectionObserver(T, {
+				...d,
+				root: t
+			}), a = r instanceof NodeList ? r[0] : r;
+			v.current = i, i.observe(a);
+		}, [T]),
+		reset: w,
+		...f
+	};
+}
+//#endregion
+//#region src/useIntersectionObserverGroup.ts
+function o(t) {
+	let { root: a = null, once: o = !1, keyAttribute: s = "data-intersection-key", onEntered: c, onExited: l, onChange: u, ...d } = t || {}, [f, p] = r(() => ({})), m = n(o), h = n(a), g = n(null), _ = n(null), v = n(null), y = n({}), b = i(c), x = i(l), S = i(u), C = e(() => {
+		_.current?.disconnect(), v.current?.disconnect();
+	}, []), w = e((e) => {
+		if (!g.current) {
+			console.warn("[use-intersection-observer-group] 컨테이너가 없습니다. reset이 실패했습니다.");
+			return;
+		}
+		if (e) {
+			let t = g.current.querySelector(`[${s}="${e}"]`);
+			t instanceof Element && (_.current?.unobserve(t), y.current[e] = !1, p((t) => ({
+				...t,
+				[e]: {
+					isVisible: !1,
+					hasEntered: !1
+				}
+			})), _.current?.observe(t));
+		} else {
+			_.current?.disconnect(), y.current = {}, p(() => ({}));
+			let e = g.current.querySelectorAll(`[${s}]`), t = h.current === "container" ? g.current : null, n = new IntersectionObserver(E, {
+				...d,
+				root: t
+			});
+			_.current = n, e.forEach((e) => {
+				n.observe(e);
+			});
+		}
+	}, []), T = e((e) => {
+		e.forEach((e) => {
+			e.addedNodes.forEach((e) => {
+				e instanceof Element && [...e.hasAttribute(s) ? [e] : [], ...Array.from(e.querySelectorAll(`[${s}]`))].forEach((e) => {
+					_.current?.observe(e);
+				});
+			}), e.removedNodes.forEach((e) => {
+				e instanceof Element && [...e.hasAttribute(s) ? [e] : [], ...Array.from(e.querySelectorAll(`[${s}]`))].forEach((e) => {
+					let t = e.getAttribute(s);
+					t && (_.current?.unobserve(e), delete y.current[t], p((e) => {
+						let n = { ...e };
+						return delete n[t], n;
+					}));
+				});
+			});
+		});
+	}, []), E = e((e, t) => {
+		p((n) => {
+			let r = { ...n };
+			return e.forEach((e) => {
+				let i = e.target.getAttribute(s);
+				if (!i) {
+					console.warn(`[use-intersection-observer-group] ${s} 속성이 없습니다.`);
+					return;
+				}
+				let a = e.isIntersecting, o = n[i];
+				S.current?.(i, a ? "enter" : "exit", e, t), a ? (y.current[i] ||= m.current, b.current?.(i, e, t), r[i] = {
+					isVisible: a,
+					hasEntered: !0
+				}) : (x.current?.(i, e, t), r[i] = {
+					isVisible: a,
+					hasEntered: o?.hasEntered ?? !1
+				}, y.current[i] && t.unobserve(e.target));
+			}), r;
+		});
+	}, []);
+	return {
+		setContainerRef: e((e) => {
+			if (!e) {
+				g.current = null, C();
+				return;
+			}
+			g.current = e;
+			let t = h.current === "container" ? e : null, n = e.querySelectorAll(`[${s}]`), r = new IntersectionObserver(E, {
+				...d,
+				root: t
+			});
+			_.current = r;
+			let i = new MutationObserver(T);
+			i.observe(e, {
+				childList: !0,
+				subtree: !0
+			}), v.current = i, n.length !== 0 && n.forEach((e) => {
+				r.observe(e);
+			});
+		}, [E]),
+		reset: w,
+		states: f
+	};
+}
+//#endregion
+export { a as useIntersectionObserver, o as useIntersectionObserverGroup };

package/dist/types.d.ts

@@ -0,0 +1,4 @@
+export type IntersectionBaseOptions = {
+    root?: "container" | null;
+    once?: boolean;
+} & Omit<IntersectionObserverInit, "root">;

package/dist/useIntersectionObserver.d.ts

@@ -0,0 +1,15 @@
+import { RefCallback } from 'react';
+import { IntersectionBaseOptions } from './types';
+type IntersectionObserverOption = IntersectionBaseOptions & {
+    targetSelector?: string;
+    onEntered?: (entry: IntersectionObserverEntry, observer: IntersectionObserver) => void;
+    onExited?: (entry: IntersectionObserverEntry, observer: IntersectionObserver) => void;
+    onChange?: (type: "enter" | "exit", entry: IntersectionObserverEntry, observer: IntersectionObserver) => void;
+};
+declare function useIntersectionObserver(options?: IntersectionObserverOption): {
+    isVisible: boolean;
+    hasEntered: boolean;
+    setContainerRef: RefCallback<HTMLElement>;
+    reset: () => void;
+};
+export { useIntersectionObserver };

package/dist/useIntersectionObserverGroup.d.ts

@@ -0,0 +1,19 @@
+import { RefCallback } from 'react';
+import { IntersectionBaseOptions } from './types';
+type IntersectionGroupOption = IntersectionBaseOptions & {
+    keyAttribute?: string;
+    onEntered?: (key: string, entry: IntersectionObserverEntry, observer: IntersectionObserver) => void;
+    onExited?: (key: string, entry: IntersectionObserverEntry, observer: IntersectionObserver) => void;
+    onChange?: (key: string, type: "enter" | "exit", entry: IntersectionObserverEntry, observer: IntersectionObserver) => void;
+};
+type TargetState = {
+    isVisible: boolean;
+    hasEntered: boolean;
+};
+type GroupStates = Record<string, TargetState>;
+declare function useIntersectionObserverGroup(options?: IntersectionGroupOption): {
+    setContainerRef: RefCallback<HTMLElement>;
+    reset: (key?: string) => void;
+    states: GroupStates;
+};
+export { useIntersectionObserverGroup };

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@leejaehyeok/use-intersection-observer",
+  "version": "0.1.0",
+  "description": "React hooks for observing element visibility using the Intersection Observer API. Supports single element and multiple elements tracking with lifecycle callbacks.",
+  "author": "leejh1316",
+  "license": "MIT",
+  "homepage": "https://github.com/leejh1316/react-hooks/tree/master/packages/use-intersection-observer#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/leejh1316/react-hooks.git",
+    "directory": "packages/use-intersection-observer"
+  },
+  "bugs": {
+    "url": "https://github.com/leejh1316/react-hooks/issues"
+  },
+  "keywords": [
+    "react",
+    "hooks",
+    "intersection-observer",
+    "visibility",
+    "lazy-loading",
+    "scroll-detection"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "dependencies": {
+    "@leejaehyeok/use-latest-ref": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.14",
+    "@vitejs/plugin-react": "^6.0.1",
+    "typescript": "~6.0.2",
+    "vite": "^8.0.4",
+    "vite-plugin-dts": "^4.0.0"
+  },
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite build --watch",
+    "release": "pnpm publish --access public"
+  }
+}