react-overflow-tabs 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Baver Bozdağ
+
+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,228 @@
+# react-overflow-tabs
+
+A headless React hook to gracefully collapse overflowing tabs into a dropdown menu.  
+Works with any UI framework (Tailwind, Bootstrap, MUI, custom CSS).
+
+[![npm version](https://img.shields.io/npm/v/react-overflow-tabs.svg)](https://www.npmjs.com/package/react-overflow-tabs)  
+[![license](https://img.shields.io/npm/l/react-overflow-tabs.svg)](LICENSE)
+
+A lightweight React hook for responsive tab navigation with automatic overflow handling.  
+Perfect for building tab systems, breadcrumbs, or step navigators.
+
+---
+
+## 🎥 Demo
+
+![Demo of react-overflow-tabs](https://raw.githubusercontent.com/bawerbozdag/react-overflow-tabs/master/assets/demo.gif)
+
+---
+
+## ✨ Features
+
+- 🔗 **Headless** – no styles, works with your own UI
+- 📏 **Responsive** – detects tab overflow using `IntersectionObserver`
+- ⚡ **Lightweight** – tree-shakeable, no dependencies
+- 🎯 **Framework-agnostic** – use with Tailwind, Bootstrap, MUI, or custom CSS
+
+---
+
+## 📦 Installation
+
+```bash
+npm install react-overflow-tabs
+# or
+yarn add react-overflow-tabs
+# or
+pnpm add react-overflow-tabs
+```
+
+Peer dependencies:
+
+- `react >=18 <20`
+
+---
+
+## 🚀 Quickstart
+
+⚠️ Do not use `display: none` or move elements out of flow with `position: absolute;`
+Both will cause `IntersectionObserver` to stop tracking the element. Instead:
+
+- Use `visibility: hidden`
+
+```tsx
+import { useRef } from "react";
+import { useOverflowTabs } from "react-overflow-tabs";
+
+const Example = () => {
+    const containerRef = useRef<HTMLDivElement>(null);
+
+    const { overflowKeys, isOverflowing } = useOverflowTabs({
+        container: containerRef,
+    });
+
+    const KEYS = [
+        "home-1",
+        "profile-1",
+        "settings-1",
+        "home-2",
+        "profile-2",
+        "settings-2",
+        "home-3",
+        "profile-3",
+        "settings-3",
+        "home-4",
+        "profile-4",
+        "settings-4",
+    ];
+
+    return (
+        <div
+            ref={containerRef}
+            style={{
+                display: "flex",
+                gap: 12,
+                overflow: "hidden",
+            }}
+        >
+            {KEYS.map((k) => (
+                <button
+                    key={k}
+                    data-overflow-key={k}
+                    style={{
+                        whiteSpace: "nowrap",
+                        visibility: overflowKeys.includes(k) ? "hidden" : "visible",
+                    }}
+                >
+                    {k}
+                </button>
+            ))}
+            {isOverflowing && (
+                <div style={{ marginLeft: "auto" }}>
+                    <div
+                        style={{
+                            position: "absolute",
+                            marginTop: 40,
+                            right: 4,
+                            border: "1px solid red",
+                            padding: 6,
+                        }}
+                    >
+                        {overflowKeys.map((key) => (
+                            <div key={key} style={{ padding: "6px 10px", whiteSpace: "nowrap" }}>
+                                {key}
+                            </div>
+                        ))}
+                    </div>
+                </div>
+            )}
+        </div>
+    );
+};
+```
+
+---
+
+## ⚙️ API
+
+### `useOverflowTabs(options: IOverflowTabsOptions): IOverflowState`
+
+#### Options (`IOverflowTabsOptions`)
+
+| Option        | Type                                      | Default                 | Description                                                                 |
+| ------------- | ----------------------------------------- | ----------------------- | --------------------------------------------------------------------------- |
+| `container`   | `RefObject<HTMLElement>` \| `HTMLElement` | **required**            | The container element to observe.                                           |
+| `tabSelector` | `string`                                  | `"[data-overflow-key]"` | Selector for tab elements. Each tab must have a unique `data-overflow-key`. |
+| `disabled`    | `boolean`                                 | `false`                 | Temporarily disable overflow tracking.                                      |
+
+#### Return (`IOverflowState`)
+
+| Key             | Type       | Description                                      |
+| --------------- | ---------- | ------------------------------------------------ |
+| `visibleKeys`   | `string[]` | Keys of tabs currently visible in the container. |
+| `overflowKeys`  | `string[]` | Keys of tabs pushed into overflow (hidden).      |
+| `isOverflowing` | `boolean`  | Whether overflow is currently happening.         |
+
+---
+
+## 🛠 Example with Tailwind
+
+```tsx
+import { useRef } from "react";
+import useOverflowTabs from "./useOverflowTabs";
+
+const Example = () => {
+    const containerRef = useRef<HTMLDivElement>(null);
+
+    const { overflowKeys, isOverflowing } = useOverflowTabs({
+        container: containerRef,
+    });
+
+    const KEYS = [
+        "home-1",
+        "profile-1",
+        "settings-1",
+        "home-2",
+        "profile-2",
+        "settings-2",
+        "home-3",
+        "profile-3",
+        "settings-3",
+        "home-4",
+        "profile-4",
+        "settings-4",
+    ];
+
+    return (
+        <div ref={containerRef} className="flex gap-3 overflow-hidden">
+            {KEYS.map((k) => (
+                <button
+                    key={k}
+                    data-overflow-key={k}
+                    className={"p-2 whitespace-nowrap border" + (overflowKeys.includes(k) ? " invisible" : "")}
+                >
+                    {k}
+                </button>
+            ))}
+
+            {isOverflowing && (
+                <div className="ml-auto">
+                    <div className="absolute right-4 mt-14 border">
+                        {overflowKeys.map((key) => (
+                            <div key={key} className="p-2 whitespace-nowrap">
+                                {key}
+                            </div>
+                        ))}
+                    </div>
+                </div>
+            )}
+        </div>
+    );
+};
+```
+
+---
+
+## 📖 Notes
+
+- Uses **`IntersectionObserver`** under the hood → supported in modern browsers.
+- `threshold: 0.999` by default → requires _full visibility_ to count as visible.
+- Works with **RTL** layouts, as it only tracks visibility.
+
+---
+
+## 🤝 Contributing
+
+Contributions, issues, and feature requests are welcome!  
+Feel free to open an [issue](https://github.com/bawerbozdag/react-overflow-tabs/issues) or submit a PR.
+
+1. Fork the repo
+2. Create your feature branch (`git checkout -b feature/my-feature`)
+3. Commit your changes (`git commit -m 'Add some feature'`)
+4. Push to the branch (`git push origin feature/my-feature`)
+5. Open a Pull Request
+
+---
+
+## 📜 License
+
+MIT © [Baver Bozdağ](https://github.com/bawerbozdag)

package/dist/index.d.mts

@@ -0,0 +1,27 @@
+import { RefObject } from 'react';
+
+type TOverflowDirection = "start" | "end";
+interface IOverflowTabsOptions<T extends HTMLElement = HTMLElement> {
+    /**
+     * Container element:
+     * - React ref (current: T | null)
+     * - or direct element (via query selector)
+     */
+    container: RefObject<T | null> | T;
+    /**
+     * Attribute name for tabs.
+     * Each tab must have this attribute with a unique value.
+     * Default: "data-overflow-key" or "[data-overflow-key]"
+     */
+    tabSelector?: string;
+    disabled?: boolean;
+}
+interface IOverflowState {
+    visibleKeys: string[];
+    overflowKeys: string[];
+    isOverflowing: boolean;
+}
+
+declare const useOverflowTabs: <T extends HTMLElement = HTMLElement>(options: IOverflowTabsOptions<T>) => IOverflowState;
+
+export { type IOverflowState, type IOverflowTabsOptions, type TOverflowDirection, useOverflowTabs };

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+import { RefObject } from 'react';
+
+type TOverflowDirection = "start" | "end";
+interface IOverflowTabsOptions<T extends HTMLElement = HTMLElement> {
+    /**
+     * Container element:
+     * - React ref (current: T | null)
+     * - or direct element (via query selector)
+     */
+    container: RefObject<T | null> | T;
+    /**
+     * Attribute name for tabs.
+     * Each tab must have this attribute with a unique value.
+     * Default: "data-overflow-key" or "[data-overflow-key]"
+     */
+    tabSelector?: string;
+    disabled?: boolean;
+}
+interface IOverflowState {
+    visibleKeys: string[];
+    overflowKeys: string[];
+    isOverflowing: boolean;
+}
+
+declare const useOverflowTabs: <T extends HTMLElement = HTMLElement>(options: IOverflowTabsOptions<T>) => IOverflowState;
+
+export { type IOverflowState, type IOverflowTabsOptions, type TOverflowDirection, useOverflowTabs };

package/dist/index.js

@@ -0,0 +1 @@
+"use strict";var u=Object.defineProperty;var E=Object.getOwnPropertyDescriptor;var I=Object.getOwnPropertyNames;var K=Object.prototype.hasOwnProperty;var h=(e,t)=>{for(var o in t)u(e,o,{get:t[o],enumerable:!0})},x=(e,t,o,a)=>{if(t&&typeof t=="object"||typeof t=="function")for(let r of I(t))!K.call(e,r)&&r!==o&&u(e,r,{get:()=>t[r],enumerable:!(a=E(t,r))||a.enumerable});return e};var z=e=>x(u({},"__esModule",{value:!0}),e);var M={};h(M,{useOverflowTabs:()=>w});module.exports=z(M);var l=require("react");var A=e=>e?typeof e=="object"&&"current"in e?e.current:e:null,y=A;var H=e=>{let t=e!=null?e:"[data-overflow-key]";return t.startsWith("[")&&t.endsWith("]")?t.slice(1,-1):t},p=H;var L=e=>{let[t,o]=(0,l.useState)([]),[a,r]=(0,l.useState)([]),[g,b]=(0,l.useState)(!1);return(0,l.useEffect)(()=>{let c=y(e.container);if(!c)return;let m=p(e.tabSelector),v=Array.from(c.querySelectorAll(`[${m}]`));if(o(v.map(f=>f.getAttribute(m))),e.disabled==!0){r([]),b(!1);return}let O=new Set,i=new Set,T=new IntersectionObserver(f=>{let d=!1;for(let n of f){let s=n.target.getAttribute(m);if(!s)continue;O.add(s);let S=i.size;n.intersectionRatio<1?i.add(s):i.delete(s),i.size!=S&&(d=!0)}if(d){let n=Array.from(i);r(n.reverse()),o(Array.from(O).filter(s=>!n.includes(s))),b(n.length>0)}},{root:c,threshold:.999});return v.forEach(f=>T.observe(f)),()=>{T.disconnect()}},[e.container,e.tabSelector,e.disabled]),{visibleKeys:t,overflowKeys:a,isOverflowing:g}},w=L;0&&(module.exports={useOverflowTabs});

package/dist/index.mjs

@@ -0,0 +1 @@
+import{useEffect as E,useState as f}from"react";var g=e=>e?typeof e=="object"&&"current"in e?e.current:e:null,T=g;var S=e=>{let t=e!=null?e:"[data-overflow-key]";return t.startsWith("[")&&t.endsWith("]")?t.slice(1,-1):t},d=S;var I=e=>{let[t,a]=f([]),[y,c]=f([]),[p,m]=f(!1);return E(()=>{let l=T(e.container);if(!l)return;let i=d(e.tabSelector),u=Array.from(l.querySelectorAll(`[${i}]`));if(a(u.map(s=>s.getAttribute(i))),e.disabled==!0){c([]),m(!1);return}let b=new Set,n=new Set,v=new IntersectionObserver(s=>{let O=!1;for(let r of s){let o=r.target.getAttribute(i);if(!o)continue;b.add(o);let w=n.size;r.intersectionRatio<1?n.add(o):n.delete(o),n.size!=w&&(O=!0)}if(O){let r=Array.from(n);c(r.reverse()),a(Array.from(b).filter(o=>!r.includes(o))),m(r.length>0)}},{root:l,threshold:.999});return u.forEach(s=>v.observe(s)),()=>{v.disconnect()}},[e.container,e.tabSelector,e.disabled]),{visibleKeys:t,overflowKeys:y,isOverflowing:p}},K=I;export{K as useOverflowTabs};

package/package.json

@@ -0,0 +1,79 @@
+{
+    "name": "react-overflow-tabs",
+    "version": "1.0.0",
+    "description": "A lightweight React hook for responsive tab navigation with automatic overflow handling. Works with any UI framework (Tailwind, Bootstrap, MUI, custom CSS).",
+    "main": "dist/index.js",
+    "module": "dist/index.mjs",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.mjs",
+            "require": "./dist/index.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "dist"
+    ],
+    "sideEffects": false,
+    "scripts": {
+        "build": "tsup",
+        "format": "prettier --write ./**/*.{js,jsx,ts,tsx,cjs,json,css,scss}",
+        "typecheck": "tsc -p tsconfig.json --noEmit"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/bawerbozdag/react-overflow-tabs.git"
+    },
+    "keywords": [
+        "react",
+        "tabs",
+        "overflow",
+        "dropdown",
+        "headless",
+        "hook",
+        "responsive",
+        "navigation",
+        "responsive-tabs",
+        "tab-navigation",
+        "react-tabs-overflow",
+        "intersection-observer",
+        "resize-observer",
+        "ui-agnostic",
+        "tabbar",
+        "navbar",
+        "bootstrap",
+        "tailwind",
+        "mui",
+        "menu",
+        "react-hook",
+        "overflow-tabs",
+        "headless-ui"
+    ],
+    "author": "Baver Bozdağ",
+    "license": "MIT",
+    "bugs": {
+        "url": "https://github.com/bawerbozdag/react-overflow-tabs/issues"
+    },
+    "homepage": "https://github.com/bawerbozdag/react-overflow-tabs#readme",
+    "peerDependencies": {
+        "react": ">=18 <20"
+    },
+    "devDependencies": {
+        "@semantic-release/changelog": "^6.0.3",
+        "@semantic-release/git": "^10.0.1",
+        "@semantic-release/github": "^11.0.4",
+        "@semantic-release/npm": "^12.0.2",
+        "@types/react": "^19.1.10",
+        "conventional-changelog-conventionalcommits": "^9.1.0",
+        "prettier": "^3.6.2",
+        "react": "^19.1.1",
+        "semantic-release": "^24.2.7",
+        "tsup": "^8.5.0",
+        "typescript": "^5.9.2"
+    },
+    "engines": {
+        "node": ">=18"
+    }
+}