use-smooth-scroll-restore 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UdhayaKumar
+
+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,58 @@
+# 🌊 use-smooth-scroll-restore
+
+[![npm version](https://img.shields.io/npm/v/use-smooth-scroll-restore?color=blue)](https://www.npmjs.com/package/use-smooth-scroll-restore)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/use-smooth-scroll-restore)](https://bundlephobia.com/package/use-smooth-scroll-restore)
+[![license](https://img.shields.io/npm/l/use-smooth-scroll-restore)](https://github.com/udhayavirat18/use-smooth-scroll-restore/blob/main/LICENSE)
+
+The ultimate React hook for seamless scroll position restoration. Engineered to fix the "jump-to-top" bug across routes, tabs, and browser back/forward buttons.
+
+## ✨ Why Every App Needs This
+
+Most SPAs (Single Page Apps) lose the user's scroll position when they navigate away or hit the back button. `use-smooth-scroll-restore` provides a **privacy-first, flicker-free** solution.
+
+- **✅ Browser Back/Forward:** Lands exactly where the user left off.
+- **✅ Refresh Persistence:** Remembers position even after a hard refresh.
+- **✅ Mobile Safari Fix:** Optimized for iOS scroll-jumping edge cases.
+- **✅ Performance First:** Throttled event listeners + `requestAnimationFrame`.
+- **✅ Zero Dependencies:** Tiny footprint (< 1kB gzipped).
+
+## 📦 Installation
+
+```bash
+npm install use-smooth-scroll-restore
+```
+
+## 🚀 Usage
+
+Simply call the hook in your top-level page components or a layout wrapper.
+
+```typescript
+import { useSmoothScrollRestore } from 'use-smooth-scroll-restore';
+
+function BlogPage() {
+  // Remembers scroll position automatically
+  useSmoothScrollRestore();
+
+  return (
+    <main>
+      <h1>Long Content...</h1>
+    </main>
+  );
+}
+```
+
+## ⚙️ Advanced Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `throttle` | `number` | `100` | Delay (ms) between scroll tracking updates. |
+| `key` | `string` | `'scroll-restore'` | Custom prefix for sessionStorage keys. |
+| `isEnabled` | `boolean` | `true` | Programmatically enable/disable tracking. |
+
+## 🛡️ Privacy
+
+This hook uses sessionStorage, meaning all scroll data is wiped when the tab is closed. No cookies, no local storage, and zero tracking.
+
+## 🧠 How it Works
+
+By leveraging `useLayoutEffect` and `requestAnimationFrame`, we ensure the scroll restoration happens before the browser paints. This eliminates the "flash of top-page" content, making navigation feel native and instantaneous.

package/dist/index.cjs

@@ -0,0 +1,65 @@
+'use strict';
+
+const react = require('react');
+
+const useSmoothScrollRestore = (options = {}) => {
+  const {
+    throttle = 100,
+    key = "scroll-restore",
+    isEnabled = true
+  } = options;
+  const scrollTimer = react.useRef(null);
+  const saveScroll = react.useCallback(() => {
+    if (!isEnabled) return;
+    const path = window.location.pathname;
+    const scrollData = {
+      x: window.scrollX,
+      y: window.scrollY,
+      timestamp: Date.now()
+    };
+    const storageKey = `${key}:${path}`;
+    sessionStorage.setItem(storageKey, JSON.stringify(scrollData));
+  }, [isEnabled, key]);
+  const restoreScroll = react.useCallback(() => {
+    if (!isEnabled) return;
+    const path = window.location.pathname;
+    const storageKey = `${key}:${path}`;
+    const saved = sessionStorage.getItem(storageKey);
+    if (saved) {
+      try {
+        const { x, y } = JSON.parse(saved);
+        requestAnimationFrame(() => {
+          window.scrollTo({
+            top: y,
+            left: x,
+            behavior: "auto"
+            // 'auto' is faster and more reliable for restoration
+          });
+        });
+      } catch (e) {
+        console.warn("Failed to restore scroll position", e);
+      }
+    }
+  }, [isEnabled, key]);
+  react.useEffect(() => {
+    if (!isEnabled) return;
+    const handleScroll = () => {
+      if (scrollTimer.current) return;
+      scrollTimer.current = setTimeout(() => {
+        saveScroll();
+        scrollTimer.current = null;
+      }, throttle);
+    };
+    window.addEventListener("scroll", handleScroll, { passive: true });
+    return () => {
+      window.removeEventListener("scroll", handleScroll);
+      if (scrollTimer.current) clearTimeout(scrollTimer.current);
+    };
+  }, [saveScroll, throttle, isEnabled]);
+  react.useLayoutEffect(() => {
+    restoreScroll();
+  }, [restoreScroll]);
+  return { saveScroll, restoreScroll };
+};
+
+exports.useSmoothScrollRestore = useSmoothScrollRestore;

package/dist/index.d.cts

@@ -0,0 +1,12 @@
+interface ScrollOptions {
+    throttle?: number;
+    key?: string;
+    isEnabled?: boolean;
+}
+declare const useSmoothScrollRestore: (options?: ScrollOptions) => {
+    saveScroll: () => void;
+    restoreScroll: () => void;
+};
+
+export { useSmoothScrollRestore };
+export type { ScrollOptions };

package/dist/index.d.mts

@@ -0,0 +1,12 @@
+interface ScrollOptions {
+    throttle?: number;
+    key?: string;
+    isEnabled?: boolean;
+}
+declare const useSmoothScrollRestore: (options?: ScrollOptions) => {
+    saveScroll: () => void;
+    restoreScroll: () => void;
+};
+
+export { useSmoothScrollRestore };
+export type { ScrollOptions };

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+interface ScrollOptions {
+    throttle?: number;
+    key?: string;
+    isEnabled?: boolean;
+}
+declare const useSmoothScrollRestore: (options?: ScrollOptions) => {
+    saveScroll: () => void;
+    restoreScroll: () => void;
+};
+
+export { useSmoothScrollRestore };
+export type { ScrollOptions };

package/dist/index.mjs

@@ -0,0 +1,63 @@
+import { useRef, useCallback, useEffect, useLayoutEffect } from 'react';
+
+const useSmoothScrollRestore = (options = {}) => {
+  const {
+    throttle = 100,
+    key = "scroll-restore",
+    isEnabled = true
+  } = options;
+  const scrollTimer = useRef(null);
+  const saveScroll = useCallback(() => {
+    if (!isEnabled) return;
+    const path = window.location.pathname;
+    const scrollData = {
+      x: window.scrollX,
+      y: window.scrollY,
+      timestamp: Date.now()
+    };
+    const storageKey = `${key}:${path}`;
+    sessionStorage.setItem(storageKey, JSON.stringify(scrollData));
+  }, [isEnabled, key]);
+  const restoreScroll = useCallback(() => {
+    if (!isEnabled) return;
+    const path = window.location.pathname;
+    const storageKey = `${key}:${path}`;
+    const saved = sessionStorage.getItem(storageKey);
+    if (saved) {
+      try {
+        const { x, y } = JSON.parse(saved);
+        requestAnimationFrame(() => {
+          window.scrollTo({
+            top: y,
+            left: x,
+            behavior: "auto"
+            // 'auto' is faster and more reliable for restoration
+          });
+        });
+      } catch (e) {
+        console.warn("Failed to restore scroll position", e);
+      }
+    }
+  }, [isEnabled, key]);
+  useEffect(() => {
+    if (!isEnabled) return;
+    const handleScroll = () => {
+      if (scrollTimer.current) return;
+      scrollTimer.current = setTimeout(() => {
+        saveScroll();
+        scrollTimer.current = null;
+      }, throttle);
+    };
+    window.addEventListener("scroll", handleScroll, { passive: true });
+    return () => {
+      window.removeEventListener("scroll", handleScroll);
+      if (scrollTimer.current) clearTimeout(scrollTimer.current);
+    };
+  }, [saveScroll, throttle, isEnabled]);
+  useLayoutEffect(() => {
+    restoreScroll();
+  }, [restoreScroll]);
+  return { saveScroll, restoreScroll };
+};
+
+export { useSmoothScrollRestore };

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "use-smooth-scroll-restore",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "The ultimate React hook for seamless scroll position restoration across routes, tabs, and sessions. Zero-config, lightweight, and flicker-free.",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "unbuild",
+    "dev": "unbuild --stub",
+    "lint": "tsc --noEmit"
+  },
+  "keywords": [
+    "react",
+    "react-hook",
+    "scroll-restoration",
+    "scroll-restore",
+    "nextjs",
+    "react-router",
+    "ux",
+    "scroll-position",
+    "persistence",
+    "flicker-free",
+    "smooth-scroll"
+  ],
+  "author": "UdhayaKumar",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/udhayavirat18/use-smooth-scroll-restore"
+  },
+  "bugs": {
+    "url": "https://github.com/udhayavirat18/use-smooth-scroll-restore/issues"
+  },
+  "homepage": "https://github.com/udhayavirat18/use-smooth-scroll-restore#readme",
+  "devDependencies": {
+    "@types/react": "^19.2.14",
+    "typescript": "^5.9.3",
+    "unbuild": "^3.6.1"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  }
+}