🧠 scroll-recaller

A tiny JavaScript utility to remember and restore scroll position across pages or sessions — perfect for SPAs, long-form content, and readers who hate losing their place.

🚀 Features

• 🔄 Save scroll position per page or route
• 🧭 Restore it on return or refresh
• ⚙️ Customizable scroll key
• ⏱ Optional auto-expiry for saved positions
• 🪶 Zero dependencies, ultra-lightweight
• 🧙 Works in Vanilla JS, React, Vue, Astro, and more

📦 Installation

npm install scroll-recaller

🧪 Basic Usage

import { createScrollManager } from 'scroll-recaller';

const scrollManager = createScrollManager({
  useSession: false,             // Use sessionStorage instead of localStorage
  debounceMs: 200,               // Debounce scroll saving
  expiry: 1000 * 60 * 60 * 6,    // Expire scroll data after 6 hours
  key: () => window.location.pathname + window.search // Optional: custom scroll key
});

// Restore scroll on page load
scrollManager.restoreScroll();

// Start tracking scroll events
const untrack = scrollManager.trackScroll();

// Optional: Stop tracking later
// untrack();

📚 API

createScrollManager(options?)

Returns a scroll manager with methods to manage scroll position.

Returned Methods

saveScroll()

Saves the current scroll position manually.

restoreScroll()

Scrolls to the previously saved position (if exists and not expired).

clearScroll()

Clears the saved scroll position for the current key.

trackScroll()

Starts automatically saving the scroll position on scroll events.

Returns a cleanup function () => void to stop tracking.

🧙 Use Cases

• SPAs — Persist scroll across dynamic page transitions
• Documentation — Restore reader’s place on reload
• Ebooks / Articles — Let users resume from where they left off
• Forms — Save scroll when navigating away