react-use-section-observer 1.0.0

package/README.md

@@ -0,0 +1,38 @@
+# react-use-section-observer
+
+A lightweight React hook to track element visibility using the Intersection Observer API and automatically apply an active class to matching links.
+
+---
+
+## 🎥 Demo
+
+![Preview](./docs/preview.gif)
+
+---
+
+## ✨ Features
+
+- Tracks visibility of multiple sections
+- Automatically updates matching anchor links
+- Supports custom root containers
+- Supports multiple class names (e.g. Tailwind)
+- No DOM mutation via `data-*`
+- No external dependencies
+- Fully typed (TypeScript)
+- Adjustable to your DOM structure
+
+---
+
+## ⚠️ Limitations
+
+- Only vertical scrolling (Y-axis) is supported.
+- Links must use the `href="#id"` format.
+- Requires browser support for `IntersectionObserver`.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install react-use-section-observer
+```

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+import { type DependencyList } from "react";
+export interface SectionObserverOptions {
+    /**
+     * Array of section IDs to observe.
+     * Each ID should correspond to an element in the DOM that you want to track.
+     */
+    ids: string[];
+    /**
+     * Enable or disable the observer.
+     * If your sections are dynamically added or removed, you can set this to false
+     * until the sections are ready, then set it to true to start observing.
+     */
+    enabled?: boolean;
+    /**
+     * The root element for the Intersection Observer.
+     * Defaults to the viewport if not specified.
+     */
+    viewportRoot?: Element | null;
+    /** Class name(s) to apply to the active link */
+    activeClassName?: string;
+    /**
+     * Callback function invoked when the active element changes.
+     * Receives an object containing the active link and the corresponding active section element.
+     */
+    onActiveChange?: (params: {
+        link: Element;
+        activeElement: Element | null;
+    }) => void;
+    /**
+     * Optional accessors to customize how links are selected and how active state is determined.
+     * This allows you to adapt the hook to different DOM structures and link formats.
+     */
+    linkAccessors?: {
+        getLinkSelector: (id: string) => string;
+        getIsLinkActive: (params: {
+            link: Element;
+            activeElement: Element;
+        }) => boolean;
+    };
+}
+/**
+ * React hook to observe sections and update corresponding links
+ * based on their visibility in the viewport.
+ */
+export declare function useSectionObserver({ ids, enabled, viewportRoot, activeClassName, onActiveChange, linkAccessors: linkAccessor, }: SectionObserverOptions, deps?: DependencyList): void;

package/dist/index.es.js

@@ -0,0 +1,65 @@
+import { useRef as b, useEffect as p } from "react";
+function L({
+  ids: n,
+  enabled: r = !0,
+  viewportRoot: t = null,
+  activeClassName: o = "active",
+  onActiveChange: l,
+  linkAccessors: g
+}, d = []) {
+  const {
+    getLinkSelector: v = (c) => `a[href$="#${c}"]`,
+    getIsLinkActive: E = ({
+      link: c,
+      activeElement: i
+    }) => c.getAttribute("href")?.endsWith(`#${i?.id}`)
+  } = g || {}, u = b(/* @__PURE__ */ new Map());
+  p(() => {
+    if (!r || !n.length) return;
+    const c = n.map((e) => document.getElementById(e)).filter((e) => !!e), i = n.map((e) => document.querySelector(v(e))).filter((e) => !!e), a = new IntersectionObserver(
+      (e) => {
+        e.forEach((s) => {
+          u.current.set(s.target, s);
+        });
+        const f = A(u.current);
+        i.forEach((s) => {
+          const h = f && E({ link: s, activeElement: f });
+          m(s, o, !!h), h && l && l({ link: s, activeElement: f });
+        });
+      },
+      {
+        root: t,
+        threshold: B()
+      }
+    );
+    return c.forEach((e) => a.observe(e)), () => {
+      a.disconnect(), u.current.clear(), i.forEach((e) => m(e, o, !1));
+    };
+  }, [
+    n.join(","),
+    r,
+    t,
+    o,
+    l,
+    ...d
+  ]);
+}
+function A(n) {
+  const r = Array.from(n.values()).filter(
+    (t) => t.isIntersecting
+  );
+  return r.length ? (r.sort((t, o) => o.intersectionRatio - t.intersectionRatio), r[0].target) : null;
+}
+function m(n, r, t) {
+  const o = r.trim().split(/\s+/);
+  n.classList[t ? "add" : "remove"](...o);
+}
+function B(n = 0.1) {
+  const r = [];
+  for (let t = 0; t <= 1; t += n)
+    r.push(Number(t.toFixed(2)));
+  return r;
+}
+export {
+  L as useSectionObserver
+};

package/dist/index.umd.js

@@ -0,0 +1 @@
+(function(o,i){typeof exports=="object"&&typeof module<"u"?i(exports,require("react")):typeof define=="function"&&define.amd?define(["exports","react"],i):(o=typeof globalThis<"u"?globalThis:o||self,i(o.useSectionObserver={},o.React))})(this,(function(o,i){"use strict";function g({ids:n,enabled:r=!0,viewportRoot:t=null,activeClassName:s="active",onActiveChange:l,linkAccessors:E},S=[]){const{getLinkSelector:y=u=>`a[href$="#${u}"]`,getIsLinkActive:O=({link:u,activeElement:f})=>u.getAttribute("href")?.endsWith(`#${f?.id}`)}=E||{},d=i.useRef(new Map);i.useEffect(()=>{if(!r||!n.length)return;const u=n.map(e=>document.getElementById(e)).filter(e=>!!e),f=n.map(e=>document.querySelector(y(e))).filter(e=>!!e),m=new IntersectionObserver(e=>{e.forEach(c=>{d.current.set(c.target,c)});const a=p(d.current);f.forEach(c=>{const b=a&&O({link:c,activeElement:a});h(c,s,!!b),b&&l&&l({link:c,activeElement:a})})},{root:t,threshold:v()});return u.forEach(e=>m.observe(e)),()=>{m.disconnect(),d.current.clear(),f.forEach(e=>h(e,s,!1))}},[n.join(","),r,t,s,l,...S])}function p(n){const r=Array.from(n.values()).filter(t=>t.isIntersecting);return r.length?(r.sort((t,s)=>s.intersectionRatio-t.intersectionRatio),r[0].target):null}function h(n,r,t){const s=r.trim().split(/\s+/);n.classList[t?"add":"remove"](...s)}function v(n=.1){const r=[];for(let t=0;t<=1;t+=n)r.push(Number(t.toFixed(2)));return r}o.useSectionObserver=g,Object.defineProperty(o,Symbol.toStringTag,{value:"Module"})}));

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "react-use-section-observer",
+  "version": "1.0.0",
+  "description": "A react hook to track the visibility of elements in the viewport using Intersection Observer API",
+  "homepage": "https://github.com/theo-js/react-use-section-observer#readme",
+  "bugs": {
+    "url": "https://github.com/theo-js/react-use-section-observer/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/theo-js/react-use-section-observer.git"
+  },
+  "license": "ISC",
+  "author": {
+    "email": "dev.js.theo@gmail.com",
+    "name": "theo-js",
+    "url": "https://github.com/theo-js"
+  },
+  "main": "dist/index.umd.js",
+  "module": "dist/index.es.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build:types": "tsc",
+    "build:js": "vite build",
+    "copy:types": "xcopy types\\* dist /E /I /Y",
+    "build": "npm run build:types && npm run build:js && npm run copy:types"
+  },
+  "keywords": [
+    "react",
+    "hook",
+    "intersection-observer",
+    "visibility-tracker"
+  ],
+  "dependencies": {
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1",
+    "@vitejs/plugin-react": "^5.1.4"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "workspaces": [
+    "playground"
+  ]
+}