scroll-tracking-walkeros

A lightweight, ready-to-use utility for tracking how far a user has scrolled through an article or page.
Includes both a stateless reporting function (scrollReport) and an auto-tracking helper (initScrollTracking) that attaches scroll listeners for you.
Supports both CommonJS and ES Modules.

Originally developed to be used as a source for walkerOS, an open-source event data collection.

📦 Installation

npm install scroll-tracking-walkeros
# or
yarn add scroll-tracking-walkeros

🚀 Usage

1. scrollReport()

Returns the current scroll percentage and maximum scroll percentage reached so far.

By default, it tries to measure scroll depth against an element with the ID articlebody.
If that element is missing, it will fall back to the full document.body.

Example

import { scrollReport } from "scroll-tracking-walkeros";

const { scrollPercent, scrollMaximum } = scrollReport();
console.log(`Current: ${scrollPercent}, Max: ${scrollMaximum}`);

Returns

| Property | Type | Description | |-----------------|----------|-------------| | scrollPercent | number | Current scroll position (0–1) relative to the content height. | | scrollMaximum | number | Maximum scroll percentage reached so far (0–1). |

⚠️ Important

For accurate tracking, wrap your main scrollable content in an element with:

<div id="articlebody">
  <!-- Your content -->
</div>

2. initScrollTracking(callback)

Attaches a scroll event listener and automatically calls your callback whenever the scroll percentage changes.
Also tracks the previous scroll percentage internally.

Example (React)

import { initScrollTracking } from "scroll-tracking-walkeros";

useEffect(() => {
  const cleanup = initScrollTracking(({ scrollPercent, scrollMaximum, previousPercent }) => {
    console.log("Scrolled:", scrollPercent, "Max:", scrollMaximum, "Previous:", previousPercent);
  });

  return cleanup; // Remove listener on unmount
}, []);

Callback Parameters

| Property | Type | Description | |--------------------|------------|-------------| | scrollPercent | number | Current scroll position (0–1). | | scrollMaximum | number | Maximum scroll percentage reached so far (0–1). | | previousPercent | number? | The scroll percentage from the last callback execution, or null on first run. |

Returns

initScrollTracking returns a cleanup function to remove the scroll listener.

📄 API Reference

scrollReport()

• Type: () => { scrollPercent: number; scrollMaximum: number }
• Calculates and returns the current scroll metrics.

initScrollTracking(callback)

• Type: (callback: ({ scrollPercent, scrollMaximum, previousPercent }) => void) => () => void
• Starts automatic scroll tracking and calls your callback when values change.
• Returns a cleanup function.

🛠 Development Notes

• Designed for WalkerOS integrations but works in any browser environment.
• No dependencies — pure JavaScript.
• Uses window.scrollY and element height calculations.

📜 License

MIT - Developed by sleepycat666 for Public Value Technologies GmbH