react-sticky-kit 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Saiya
+
+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,95 @@
+# React Sticky Kit
+
+<p align="left">
+  <a href="https://www.npmjs.com/package/react-sticky-kit" target="_blank">
+    <img src="https://img.shields.io/npm/v/react-sticky-kit.svg?style=flat-square" alt="NPM Version" />
+  </a>
+  <a href="https://github.com/oe/react-sticky-kit" target="_blank">
+    <img src="https://img.shields.io/github/stars/oe/react-sticky-kit?style=flat-square" alt="GitHub Stars" />
+  </a>
+  <a href="https://github.com/oe/react-sticky-kit/actions" target="_blank">
+    <img src="https://github.com/oe/react-sticky-kit/actions/workflows/ci.yml/badge.svg" alt="Build Status" />
+  </a>
+  <a href="https://github.com/oe/react-sticky-kit/blob/main/LICENSE" target="_blank">
+    <img src="https://img.shields.io/github/license/oe/react-sticky-kit?style=flat-square" alt="License" />
+  </a>
+</p>
+
+A lightweight, flexible React sticky container and item component library. Easily create sticky headers, sections, and advanced sticky layouts with support for multiple modes and edge cases.
+
+## Features
+
+- 📦 Simple API: `<StickyContainer>` and `<StickyItem>`
+- 🧩 Supports `replace`, `stack`, and `none` sticky modes
+- 🏷️ Customizable offset, z-index (baseZIndex), and sticky logic
+- 🧪 Handles edge cases: empty sections, dynamic heights, zero-height headers, long headers, etc.
+- ⚡️ Written in TypeScript, fully typed
+- 🧪 Includes demo pages for real-world scenarios
+
+## Installation
+
+```bash
+npm install react-sticky-kit
+# or
+yarn add react-sticky-kit
+# or
+pnpm add react-sticky-kit
+```
+
+## Usage
+
+```tsx
+import { StickyContainer, StickyItem } from 'react-sticky-kit';
+import 'react-sticky-kit/dist/style.css'; // Import styles for sticky components
+
+export default function Example() {
+  return (
+    <StickyContainer offsetTop={48} defaultMode="stack" baseZIndex={300}>
+      <StickyItem>
+        <div>Sticky Header</div>
+      </StickyItem>
+      <div>Content...</div>
+      <StickyItem mode="replace">
+        <div>Another Sticky Header (replace mode)</div>
+      </StickyItem>
+      <div>More Content...</div>
+    </StickyContainer>
+  );
+}
+```
+
+## Props
+
+### `<StickyContainer />`
+| Prop                        | Type                                 | Default     | Description                                                                                 |
+|-----------------------------|--------------------------------------|-------------|---------------------------------------------------------------------------------------------|
+| `offsetTop`                 | `number`                             | `0`         | Offset from the top of the viewport                                                         |
+| `defaultMode`               | `'replace' \| 'stack' \| 'none'`     | `'replace'`| Default sticky mode for all items                                                           |
+| `baseZIndex`                | `number`                             | `200`       | Base z-index for sticky items. Should be greater than the number of sticky items.            |
+|                             |                                      |             | In `replace` mode, z-index = baseZIndex - index; in `stack` mode, z-index = baseZIndex + index. |
+| `onStickyItemsHeightChange` | `(height: number) => void`            |             | Callback when total sticky height changes                                                   |
+
+### `<StickyItem />`
+| Prop    | Type                                 | Default | Description                                 |
+|---------|--------------------------------------|---------|---------------------------------------------|
+| `mode`  | `'replace' \| 'stack' \| 'none'`     |         | Sticky mode for this item (overrides group) |
+
+## Sticky Modes
+- **replace**: Only one sticky item is visible at a time, replacing the previous.
+- **stack**: Sticky items stack on top of each other.
+- **none**: Sticky is disabled for this item.
+
+## Demo
+
+Run the demo locally:
+
+```bash
+pnpm install
+pnpm dev
+```
+
+Open [http://localhost:5173](http://localhost:5173) and switch between demo pages to explore all features and edge cases.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,50 @@
+import { default as default_2 } from 'react';
+import { JSX } from 'react/jsx-runtime';
+
+export declare interface IStickyContainerProps extends default_2.HTMLAttributes<HTMLDivElement> {
+    children: default_2.ReactNode;
+    /**
+     * The offset from the top of the viewport for sticky elements. Default is 0.
+     */
+    offsetTop?: number;
+    /**
+     * base z-index for sticky items. Default is 200. minimum z-index is 20.
+     * * - When using the `replace` mode, the z-index of a `StickyItem` is calculated as `baseZIndex` minus its index within the container.
+     * * - When using the `stack` mode, the z-index of a `StickyItem` is calculated as `baseZIndex` plus its index.
+     * * should be greater than number of sticky items in the container.
+     * * for performance reasons, when baseZIndex is changed, the component will not re-render.
+     * * use it when you need nest StickyContainer or need to change z-index of sticky items.
+     */
+    baseZIndex?: number;
+    /**
+     * Default sticky mode for the group. 'none' disables sticky behavior.
+     */
+    defaultMode?: 'replace' | 'stack' | 'none';
+    /**
+     * Callback triggered when the total height of all currently sticky items changes.
+     * @param height The total height of all sticky items inside the container.
+     */
+    onStickyItemsHeightChange?: (height: number) => void;
+}
+
+export declare interface IStickyItemProps extends default_2.HTMLAttributes<HTMLDivElement> {
+    children: default_2.ReactNode;
+    /**
+     * Sticky mode for this item. Defaults to the group's mode if not specified.
+     */
+    mode?: IStickyMode;
+}
+
+/**
+ * Sticky mode:
+ * - 'replace': This item replaces the previous sticky item; its height is set to the previous sticky item's height.
+ * - 'stack': This item stacks on top of previous sticky items; its height is set to 0.
+ * - 'none': This item is not sticky.
+ */
+export declare type IStickyMode = 'replace' | 'stack' | 'none';
+
+export declare function StickyContainer({ children, offsetTop, baseZIndex, onStickyItemsHeightChange, defaultMode, ...rest }: IStickyContainerProps): JSX.Element;
+
+export declare function StickyItem({ mode, children, className, ...rest }: IStickyItemProps): JSX.Element;
+
+export { }

package/dist/react-sticky.es.js

@@ -0,0 +1,139 @@
+import { jsx as R } from "react/jsx-runtime";
+import { createContext as b, useContext as Z, useRef as I, useState as N, useEffect as B, useCallback as w, useMemo as T } from "react";
+const x = 20, $ = b(null);
+function _() {
+  return Z($);
+}
+function P({ mode: s, children: o, className: m, ...h }) {
+  const e = _(), S = I(null), k = I(null), [r, n] = N(!1), t = I({
+    fixedOffsetTop: (e == null ? void 0 : e.fixedOffsetTop) || 0,
+    isSticky: r,
+    baseZIndex: (e == null ? void 0 : e.baseZIndex) || x
+  });
+  return t.current.baseZIndex = (e == null ? void 0 : e.baseZIndex) || x, t.current.fixedOffsetTop = (e == null ? void 0 : e.fixedOffsetTop) || 0, t.current.isSticky = r, B(() => {
+    const u = k.current, f = S.current, a = s || (e == null ? void 0 : e.mode);
+    if (!e || !f || !u || a === "none" || !a || !e.register) {
+      n(!1);
+      return;
+    }
+    const d = {
+      el: f,
+      update: (l, i, p, C, H) => {
+        if (!l)
+          return t.current.isSticky && n(!1), 0;
+        if (i <= p) {
+          const y = u.getBoundingClientRect().height;
+          let v = p;
+          if (a === "replace" && typeof C < "u") {
+            const g = C - (p + y);
+            if (g < 0 && (v = p + g, g + y < 0))
+              return t.current.isSticky && n(!1), 0;
+          }
+          return t.current.isSticky || n(!0), u.style.top = `${v}px`, u.style.width = `${f.offsetWidth}px`, u.style.zIndex = `${t.current.baseZIndex + (a === "replace" ? -H : H)}`, f.style.height = `${y}px`, a === "replace" ? 0 : y;
+        } else
+          n(!1);
+        return 0;
+      }
+    };
+    return e.register(d);
+  }, [e == null ? void 0 : e.mode, e == null ? void 0 : e.register, s]), B(() => {
+    const u = S.current, f = k.current, a = e == null ? void 0 : e.updateStickyItemsHeight;
+    if (!r || !u || !f || !a)
+      return;
+    const c = a(f.getBoundingClientRect().height);
+    return () => {
+      O(u, ["height"]), O(f, ["top", "z-index", "width"]), c();
+    };
+  }, [r, e == null ? void 0 : e.updateStickyItemsHeight]), /* @__PURE__ */ R("div", { className: "oe-sticky-item " + (m || ""), ...h, ref: S, children: /* @__PURE__ */ R("div", { className: "oe-sticky-content " + (r ? "is-sticky" : ""), ref: k, children: o }) });
+}
+function O(s, o) {
+  o.forEach((m) => {
+    s.style.removeProperty(m);
+  });
+}
+const L = 200;
+function U({
+  children: s,
+  offsetTop: o = 0,
+  baseZIndex: m,
+  onStickyItemsHeightChange: h,
+  defaultMode: e = "replace",
+  ...S
+}) {
+  const k = I(null), r = I([]), n = I({
+    fixedOffsetTop: o,
+    defaultMode: e,
+    stickyItemsHeight: 0,
+    onStickyItemsHeightChange: h
+  });
+  n.current.onStickyItemsHeightChange = h;
+  const t = w(() => {
+    const c = k.current;
+    if (!c)
+      return;
+    const d = c.getBoundingClientRect(), l = n.current, i = l.fixedOffsetTop, p = l.stickyItemsHeight, C = !(d.top > i || d.bottom < i);
+    let H = i, y = d.bottom - (i + p);
+    y > 0 && (y = 0);
+    const v = r.current.map((g) => g.el.getBoundingClientRect().top);
+    r.current.forEach((g, E) => {
+      H += g.update(C, v[E], H + y, v[E + 1], E);
+    });
+  }, []), u = w((c) => {
+    const d = n.current.stickyItemsHeight + c;
+    return n.current.stickyItemsHeight = d, setTimeout(() => {
+      var l, i;
+      (i = (l = n.current).onStickyItemsHeightChange) == null || i.call(l, d);
+    }, 0), () => {
+      const l = n.current.stickyItemsHeight - c;
+      n.current.stickyItemsHeight = l, setTimeout(() => {
+        var i, p;
+        (p = (i = n.current).onStickyItemsHeightChange) == null || p.call(i, l);
+      }, 0);
+    };
+  }, []);
+  B(() => {
+    n.current.fixedOffsetTop = o, n.current.defaultMode = e, t();
+  }, [o, e, t]);
+  const f = w((c) => (r.current.push(c), r.current = A(r.current), t(), () => {
+    r.current = r.current.filter((d) => d !== c), t();
+  }), [t]);
+  B(() => (window.addEventListener("scroll", t, { passive: !0 }), window.addEventListener("resize", t, { passive: !0 }), () => {
+    window.removeEventListener("scroll", t), window.removeEventListener("resize", t);
+  }), [t]);
+  const a = T(() => z(m), [m]);
+  return /* @__PURE__ */ R(
+    $.Provider,
+    {
+      value: {
+        register: f,
+        baseZIndex: a,
+        updateStickyItemsHeight: u,
+        fixedOffsetTop: o,
+        mode: e
+      },
+      children: /* @__PURE__ */ R(
+        "div",
+        {
+          ...S,
+          ref: k,
+          className: "oe-sticky-container",
+          "data-mode": e,
+          children: s
+        }
+      )
+    }
+  );
+}
+function z(s) {
+  return typeof s > "u" ? L : Math.max(Number(s) || 0, x);
+}
+function A(s) {
+  return s.sort((o, m) => {
+    const h = o.el.getBoundingClientRect(), e = m.el.getBoundingClientRect();
+    return h.top - e.top;
+  });
+}
+export {
+  U as StickyContainer,
+  P as StickyItem
+};

package/dist/react-sticky.umd.js

@@ -0,0 +1 @@
+(function(p,m){typeof exports=="object"&&typeof module<"u"?m(exports,require("react/jsx-runtime"),require("react")):typeof define=="function"&&define.amd?define(["exports","react/jsx-runtime","react"],m):(p=typeof globalThis<"u"?globalThis:p||self,m(p.ReactSticky={},p.jsxRuntime,p.React))})(this,function(p,m,n){"use strict";const _=n.createContext(null);function N(){return n.useContext(_)}const A="";function O({mode:c,children:o,className:g,...S}){const e=N(),R=n.useRef(null),E=n.useRef(null),[s,i]=n.useState(!1),t=n.useRef({fixedOffsetTop:(e==null?void 0:e.fixedOffsetTop)||0,isSticky:s,baseZIndex:(e==null?void 0:e.baseZIndex)||20});return t.current.baseZIndex=(e==null?void 0:e.baseZIndex)||20,t.current.fixedOffsetTop=(e==null?void 0:e.fixedOffsetTop)||0,t.current.isSticky=s,n.useEffect(()=>{const f=E.current,d=R.current,l=c||(e==null?void 0:e.mode);if(!e||!d||!f||l==="none"||!l||!e.register){i(!1);return}const a={el:d,update:(y,r,h,v,H)=>{if(!y)return t.current.isSticky&&i(!1),0;if(r<=h){const k=f.getBoundingClientRect().height;let C=h;if(l==="replace"&&typeof v<"u"){const I=v-(h+k);if(I<0&&(C=h+I,I+k<0))return t.current.isSticky&&i(!1),0}return t.current.isSticky||i(!0),f.style.top=`${C}px`,f.style.width=`${d.offsetWidth}px`,f.style.zIndex=`${t.current.baseZIndex+(l==="replace"?-H:H)}`,d.style.height=`${k}px`,l==="replace"?0:k}else i(!1);return 0}};return e.register(a)},[e==null?void 0:e.mode,e==null?void 0:e.register,c]),n.useEffect(()=>{const f=R.current,d=E.current,l=e==null?void 0:e.updateStickyItemsHeight;if(!s||!f||!d||!l)return;const u=l(d.getBoundingClientRect().height);return()=>{x(f,["height"]),x(d,["top","z-index","width"]),u()}},[s,e==null?void 0:e.updateStickyItemsHeight]),m.jsx("div",{className:"oe-sticky-item "+(g||""),...S,ref:R,children:m.jsx("div",{className:"oe-sticky-content "+(s?"is-sticky":""),ref:E,children:o})})}function x(c,o){o.forEach(g=>{c.style.removeProperty(g)})}const b=200;function w({children:c,offsetTop:o=0,baseZIndex:g,onStickyItemsHeightChange:S,defaultMode:e="replace",...R}){const E=n.useRef(null),s=n.useRef([]),i=n.useRef({fixedOffsetTop:o,defaultMode:e,stickyItemsHeight:0,onStickyItemsHeightChange:S});i.current.onStickyItemsHeightChange=S;const t=n.useCallback(()=>{const u=E.current;if(!u)return;const a=u.getBoundingClientRect(),y=i.current,r=y.fixedOffsetTop,h=y.stickyItemsHeight,v=!(a.top>r||a.bottom<r);let H=r,k=a.bottom-(r+h);k>0&&(k=0);const C=s.current.map(I=>I.el.getBoundingClientRect().top);s.current.forEach((I,B)=>{H+=I.update(v,C[B],H+k,C[B+1],B)})},[]),f=n.useCallback(u=>{const a=i.current.stickyItemsHeight+u;return i.current.stickyItemsHeight=a,setTimeout(()=>{var y,r;(r=(y=i.current).onStickyItemsHeightChange)==null||r.call(y,a)},0),()=>{const y=i.current.stickyItemsHeight-u;i.current.stickyItemsHeight=y,setTimeout(()=>{var r,h;(h=(r=i.current).onStickyItemsHeightChange)==null||h.call(r,y)},0)}},[]);n.useEffect(()=>{i.current.fixedOffsetTop=o,i.current.defaultMode=e,t()},[o,e,t]);const d=n.useCallback(u=>(s.current.push(u),s.current=T(s.current),t(),()=>{s.current=s.current.filter(a=>a!==u),t()}),[t]);n.useEffect(()=>(window.addEventListener("scroll",t,{passive:!0}),window.addEventListener("resize",t,{passive:!0}),()=>{window.removeEventListener("scroll",t),window.removeEventListener("resize",t)}),[t]);const l=n.useMemo(()=>Z(g),[g]);return m.jsx(_.Provider,{value:{register:d,baseZIndex:l,updateStickyItemsHeight:f,fixedOffsetTop:o,mode:e},children:m.jsx("div",{...R,ref:E,className:"oe-sticky-container","data-mode":e,children:c})})}function Z(c){return typeof c>"u"?b:Math.max(Number(c)||0,20)}function T(c){return c.sort((o,g)=>{const S=o.el.getBoundingClientRect(),e=g.el.getBoundingClientRect();return S.top-e.top})}p.StickyContainer=w,p.StickyItem=O,Object.defineProperty(p,Symbol.toStringTag,{value:"Module"})});

package/dist/style.css

@@ -0,0 +1 @@
+.oe-sticky-container,.oe-sticky-item{position:relative}.oe-sticky-content{will-change:top,position}.oe-sticky-content.is-sticky{position:fixed}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "react-sticky-kit",
+  "version": "0.1.1",
+  "type": "module",
+  "description": "A lightweight, flexible React sticky container and item component library supporting multiple sticky modes, advanced layouts, and edge cases.",
+  "keywords": [
+    "react",
+    "sticky",
+    "react-sticky",
+    "sticky-container",
+    "sticky-item",
+    "z-index"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint src demo --ext .ts,.tsx,.js,.jsx",
+    "pub": "tsx ./scripts/publish.ts"
+  },
+  "files": [
+    "dist"
+  ],
+  "main": "dist/react-sticky.umd.js",
+  "module": "dist/react-sticky.es.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/react-sticky.es.js",
+      "require": "./dist/react-sticky.umd.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=17.0.0",
+    "react-dom": ">=17.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.25.0",
+    "@types/node": "^22.15.18",
+    "@types/react": "^19.1.2",
+    "@types/react-dom": "^19.1.2",
+    "@typescript-eslint/eslint-plugin": "^8.32.1",
+    "@typescript-eslint/parser": "^8.32.1",
+    "@vitejs/plugin-react": "^4.0.0",
+    "eslint": "^9.26.0",
+    "eslint-config-prettier": "^10.1.5",
+    "eslint-plugin-jsx-a11y": "^6.8.0",
+    "eslint-plugin-react": "^7.33.2",
+    "eslint-plugin-react-hooks": "^5.2.0",
+    "globals": "^16.0.0",
+    "sass": "^1.88.0",
+    "tsx": "^4.19.4",
+    "typescript": "^5.0.0",
+    "typescript-eslint": "^8.30.1",
+    "vite": "^4.0.0",
+    "vite-plugin-dts": "^4.5.4"
+  }
+}