react-detect-overflow 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rainymy
+
+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,101 @@
+# react-detect-overflow
+
+React hooks for detecting horizontal and vertical overflow on DOM elements. Reactively updates when the element is resized.
+
+## Installation
+
+```bash
+npm install react-detect-overflow
+```
+
+## Requirements
+
+- React `v16.8.0` or later
+
+---
+
+## Usage
+
+### `useDetectOverflowX`
+
+Detects horizontal overflow on an element.
+
+```tsx
+import { useDetectOverflowX } from "react-detect-overflow";
+
+function MyComponent() {
+  const { isOverflowing, amount, ratio, ref } =
+    useDetectOverflowX<HTMLDivElement>();
+
+  return (
+    <div ref={ref} style={{ width: 200, overflow: "hidden" }}>
+      {isOverflowing && <span>Overflowing by {amount}px</span>}
+      Some very long content that might overflow...
+    </div>
+  );
+}
+```
+
+### `useDetectOverflowY`
+
+Detects vertical overflow on an element.
+
+```tsx
+import { useDetectOverflowY } from "react-detect-overflow";
+
+function MyComponent() {
+  const { isOverflowing, amount, ratio, ref } =
+    useDetectOverflowY<HTMLDivElement>();
+
+  return (
+    <div ref={ref} style={{ height: 100, overflow: "hidden" }}>
+      {isOverflowing && <span>Overflowing by {amount}px</span>}
+      <p>Some very long content that might overflow vertically...</p>
+    </div>
+  );
+}
+```
+
+### Using an external ref
+
+If you already have a ref on the element, pass it in to avoid creating a second one.
+
+```tsx
+import { useRef } from "react";
+import { useDetectOverflowX } from "react-detect-overflow";
+
+function MyComponent() {
+  const ref = useRef<HTMLDivElement>(null);
+  const { isOverflowing } = useDetectOverflowX(ref);
+
+  return <div ref={ref}>{isOverflowing && <span>Overflowing!</span>}</div>;
+}
+```
+
+---
+
+### Example usage with `ratio`
+
+`ratio` is the `scrollSize / clientSize` of the element. A value of `1` means no overflow — values above `1` indicate how much larger the content is relative to the visible area. This can be used to drive animations or dynamic styles.
+
+```tsx
+/**
+ * A text title that bounces when overflowing.
+ */
+function BouncyTitle2({ title }) {
+  const { isOverflowing, amount, ratio, ref } =
+    useDetectOverflowX<HTMLDivElement>();
+
+  return (
+    <div ref={ref} className={"container"}>
+      <span
+        className={`text_content ${isOverflowing ? "bounce" : ""}`}
+        data-overflow={amount}
+        data-animation-duration={3 * ratio}
+      >
+        {title}
+      </span>
+    </div>
+  );
+}
+```

package/dist/index.cjs

@@ -0,0 +1,89 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let e = require("react");
+//#region src/overflow.tsx
+/**
+* Base hook for detecting overflow on a DOM element given axis.
+* Observes the element for size changes and recomputes overflow reactively.
+*
+* @param getSizes - A function that extracts scroll and client sizes from the element
+* @param externRef - An optional external ref to attach to the element. If not provided, an internal ref is created.
+* @returns An object containing overflow state and the ref to attach to the element
+*
+* @example
+* // Custom axis (e.g. both dimensions summed)
+* const { isOverflowing, ref } = useDetectOverflow(
+*   (el) => ({ scrollSize: el.scrollWidth, clientSize: el.clientWidth }),
+* );
+*/
+function t(t, n) {
+	let r = (0, e.useRef)(null), i = (0, e.useRef)(t), a = n ?? r;
+	(0, e.useLayoutEffect)(() => {
+		i.current = t;
+	}, [t]);
+	let [o, s] = (0, e.useState)(!1), [c, l] = (0, e.useState)(0), [u, d] = (0, e.useState)(0), f = (0, e.useCallback)((e) => {
+		let { scrollSize: t, clientSize: n } = i.current(e), r = t - n, a = n > 0 ? t / n : 0;
+		l(Math.max(0, r)), s(r > 0), d(a);
+	}, []);
+	return (0, e.useLayoutEffect)(() => {
+		let e = a.current;
+		if (!e) {
+			console.warn(`ref is not attached to React element: ${e}`);
+			return;
+		}
+		f(e);
+		let t = new ResizeObserver((e) => {
+			e[0] && f(e[0].target);
+		});
+		return t.observe(e), () => {
+			t.unobserve(e);
+		};
+	}, [a, f]), {
+		isOverflowing: o,
+		amount: c,
+		ratio: u,
+		ref: a
+	};
+}
+//#endregion
+//#region src/index.tsx
+/**
+* Detects horizontal (X-axis) overflow on a DOM element.
+* Reactively updates when the element is resized.
+*
+* @param externRef - An optional external ref. If not provided, an internal ref is created.
+* @returns `isOverflowing` — whether the element overflows horizontally
+* @returns `amount` — the number of overflowing pixels
+* @returns `ratio` — `scrollWidth / clientWidth` (1 means no overflow)
+* @returns `ref` — attach this to the element you want to observe
+*
+* @example
+* const { isOverflowing, amount, ratio, ref } = useDetectOverflowX();
+* return <div ref={ref}>...</div>;
+*/
+function n(e) {
+	return t((e) => ({
+		scrollSize: e.scrollWidth,
+		clientSize: e.clientWidth
+	}), e);
+}
+/**
+* Detects vertical (Y-axis) overflow on a DOM element.
+* Reactively updates when the element is resized.
+*
+* @param externRef - An optional external ref. If not provided, an internal ref is created.
+* @returns `isOverflowing` — whether the element overflows vertically
+* @returns `amount` — the number of overflowing pixels
+* @returns `ratio` — `scrollHeight / clientHeight` (1 means no overflow)
+* @returns `ref` — attach this to the element you want to observe
+*
+* @example
+* const { isOverflowing, amount, ratio, ref } = useDetectOverflowY();
+* return <div ref={ref}>...</div>;
+*/
+function r(e) {
+	return t((e) => ({
+		scrollSize: e.scrollHeight,
+		clientSize: e.clientHeight
+	}), e);
+}
+exports.useDetectOverflowX = n, exports.useDetectOverflowY = r;

package/dist/index.d.cts

@@ -0,0 +1,43 @@
+import { RefObject } from "react";
+
+//#region src/types.d.ts
+type DetectOverflow<T> = {
+  isOverflowing: boolean;
+  amount: number;
+  ratio: number;
+  ref: RefObject<T | null>;
+};
+//#endregion
+//#region src/index.d.ts
+/**
+ * Detects horizontal (X-axis) overflow on a DOM element.
+ * Reactively updates when the element is resized.
+ *
+ * @param externRef - An optional external ref. If not provided, an internal ref is created.
+ * @returns `isOverflowing` — whether the element overflows horizontally
+ * @returns `amount` — the number of overflowing pixels
+ * @returns `ratio` — `scrollWidth / clientWidth` (1 means no overflow)
+ * @returns `ref` — attach this to the element you want to observe
+ *
+ * @example
+ * const { isOverflowing, amount, ratio, ref } = useDetectOverflowX();
+ * return <div ref={ref}>...</div>;
+ */
+declare function useDetectOverflowX<T extends HTMLElement>(externRef?: RefObject<T | null>): DetectOverflow<T>;
+/**
+ * Detects vertical (Y-axis) overflow on a DOM element.
+ * Reactively updates when the element is resized.
+ *
+ * @param externRef - An optional external ref. If not provided, an internal ref is created.
+ * @returns `isOverflowing` — whether the element overflows vertically
+ * @returns `amount` — the number of overflowing pixels
+ * @returns `ratio` — `scrollHeight / clientHeight` (1 means no overflow)
+ * @returns `ref` — attach this to the element you want to observe
+ *
+ * @example
+ * const { isOverflowing, amount, ratio, ref } = useDetectOverflowY();
+ * return <div ref={ref}>...</div>;
+ */
+declare function useDetectOverflowY<T extends HTMLElement>(externRef?: RefObject<T | null>): DetectOverflow<T>;
+//#endregion
+export { useDetectOverflowX, useDetectOverflowY };

package/dist/index.d.mts

@@ -0,0 +1,43 @@
+import { RefObject } from "react";
+
+//#region src/types.d.ts
+type DetectOverflow<T> = {
+  isOverflowing: boolean;
+  amount: number;
+  ratio: number;
+  ref: RefObject<T | null>;
+};
+//#endregion
+//#region src/index.d.ts
+/**
+ * Detects horizontal (X-axis) overflow on a DOM element.
+ * Reactively updates when the element is resized.
+ *
+ * @param externRef - An optional external ref. If not provided, an internal ref is created.
+ * @returns `isOverflowing` — whether the element overflows horizontally
+ * @returns `amount` — the number of overflowing pixels
+ * @returns `ratio` — `scrollWidth / clientWidth` (1 means no overflow)
+ * @returns `ref` — attach this to the element you want to observe
+ *
+ * @example
+ * const { isOverflowing, amount, ratio, ref } = useDetectOverflowX();
+ * return <div ref={ref}>...</div>;
+ */
+declare function useDetectOverflowX<T extends HTMLElement>(externRef?: RefObject<T | null>): DetectOverflow<T>;
+/**
+ * Detects vertical (Y-axis) overflow on a DOM element.
+ * Reactively updates when the element is resized.
+ *
+ * @param externRef - An optional external ref. If not provided, an internal ref is created.
+ * @returns `isOverflowing` — whether the element overflows vertically
+ * @returns `amount` — the number of overflowing pixels
+ * @returns `ratio` — `scrollHeight / clientHeight` (1 means no overflow)
+ * @returns `ref` — attach this to the element you want to observe
+ *
+ * @example
+ * const { isOverflowing, amount, ratio, ref } = useDetectOverflowY();
+ * return <div ref={ref}>...</div>;
+ */
+declare function useDetectOverflowY<T extends HTMLElement>(externRef?: RefObject<T | null>): DetectOverflow<T>;
+//#endregion
+export { useDetectOverflowX, useDetectOverflowY };

package/dist/index.mjs

@@ -0,0 +1,89 @@
+import { useCallback as e, useLayoutEffect as t, useRef as n, useState as r } from "react";
+//#region src/overflow.tsx
+/**
+* Base hook for detecting overflow on a DOM element given axis.
+* Observes the element for size changes and recomputes overflow reactively.
+*
+* @param getSizes - A function that extracts scroll and client sizes from the element
+* @param externRef - An optional external ref to attach to the element. If not provided, an internal ref is created.
+* @returns An object containing overflow state and the ref to attach to the element
+*
+* @example
+* // Custom axis (e.g. both dimensions summed)
+* const { isOverflowing, ref } = useDetectOverflow(
+*   (el) => ({ scrollSize: el.scrollWidth, clientSize: el.clientWidth }),
+* );
+*/
+function i(i, a) {
+	let o = n(null), s = n(i), c = a ?? o;
+	t(() => {
+		s.current = i;
+	}, [i]);
+	let [l, u] = r(!1), [d, f] = r(0), [p, m] = r(0), h = e((e) => {
+		let { scrollSize: t, clientSize: n } = s.current(e), r = t - n, i = n > 0 ? t / n : 0;
+		f(Math.max(0, r)), u(r > 0), m(i);
+	}, []);
+	return t(() => {
+		let e = c.current;
+		if (!e) {
+			console.warn(`ref is not attached to React element: ${e}`);
+			return;
+		}
+		h(e);
+		let t = new ResizeObserver((e) => {
+			e[0] && h(e[0].target);
+		});
+		return t.observe(e), () => {
+			t.unobserve(e);
+		};
+	}, [c, h]), {
+		isOverflowing: l,
+		amount: d,
+		ratio: p,
+		ref: c
+	};
+}
+//#endregion
+//#region src/index.tsx
+/**
+* Detects horizontal (X-axis) overflow on a DOM element.
+* Reactively updates when the element is resized.
+*
+* @param externRef - An optional external ref. If not provided, an internal ref is created.
+* @returns `isOverflowing` — whether the element overflows horizontally
+* @returns `amount` — the number of overflowing pixels
+* @returns `ratio` — `scrollWidth / clientWidth` (1 means no overflow)
+* @returns `ref` — attach this to the element you want to observe
+*
+* @example
+* const { isOverflowing, amount, ratio, ref } = useDetectOverflowX();
+* return <div ref={ref}>...</div>;
+*/
+function a(e) {
+	return i((e) => ({
+		scrollSize: e.scrollWidth,
+		clientSize: e.clientWidth
+	}), e);
+}
+/**
+* Detects vertical (Y-axis) overflow on a DOM element.
+* Reactively updates when the element is resized.
+*
+* @param externRef - An optional external ref. If not provided, an internal ref is created.
+* @returns `isOverflowing` — whether the element overflows vertically
+* @returns `amount` — the number of overflowing pixels
+* @returns `ratio` — `scrollHeight / clientHeight` (1 means no overflow)
+* @returns `ref` — attach this to the element you want to observe
+*
+* @example
+* const { isOverflowing, amount, ratio, ref } = useDetectOverflowY();
+* return <div ref={ref}>...</div>;
+*/
+function o(e) {
+	return i((e) => ({
+		scrollSize: e.scrollHeight,
+		clientSize: e.clientHeight
+	}), e);
+}
+//#endregion
+export { a as useDetectOverflowX, o as useDetectOverflowY };

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "react-detect-overflow",
+  "version": "1.0.0",
+  "description": "",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "scripts": {
+    "===================== build ======================": "",
+    "build": "tsdown",
+    "====================== npm =======================": "",
+    "package:test": "npm pack --dry-run",
+    "package": "npm pack",
+    "prepack": "npm run build",
+    "==================================================": ""
+  },
+  "files": [
+    "dist/*"
+  ],
+  "keywords": [
+    "react",
+    "hooks",
+    "overflow",
+    "detect",
+    "resize"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Rainymy/react-detect-overflow.git"
+  },
+  "author": "Rainymy",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/Rainymy/react-detect-overflow/issues"
+  },
+  "homepage": "https://github.com/Rainymy/react-detect-overflow#readme",
+  "peerDependencies": {
+    "react": ">=16.8.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.6",
+    "@types/react": "^19.2.14",
+    "publint": "^0.3.18",
+    "react": "^19.2.4",
+    "tsdown": "^0.21.1"
+  },
+  "sideEffects": false
+}