Getting Started

ForesightJS is a lightweight JavaScript library with full TypeScript support that predicts user intent based on mouse movements, scroll and keyboard navigation. By analyzing cursor/scroll trajectory and tab sequences, it anticipates which elements a user is likely to interact with, allowing developers to trigger actions before the actual hover or click occurs (for example prefetching).

Understanding ForesightJS's Role:

When you over simplify prefetching it exists of three parts.

• What resource or data to load
• How the loading method and caching strategy is
• When the optimal moment to start fetching is

ForesightJS takes care of the When by predicting user intent with mouse trajectory and tab navigation. You supply the What and How inside your callback when you register an element.

Download

pnpm add js.foresight
# or
npm install js.foresight
# or
yarn add js.foresight

Which problems does ForesightJS solve?

Problem 1: On-Hover Prefetching Still Has Latency

Traditional hover-based prefetching only triggers after the user's cursor reaches an element. This approach wastes the critical 100-200ms window between when a user begins moving toward a target and when the hover event actually fires—time that could be used for prefetching.

Problem 2: Viewport-Based Prefetching is Wasteful

Many modern frameworks (like Next.js) automatically prefetch resources for all links that enter the viewport. While well-intentioned, this creates significant overhead since users typically interact with only a small fraction of visible elements. Simply scrolling up and down the Next.js homepage can trigger 1.59MB of unnecessary prefetch requests.

Problem 3: Hover-Based Prefetching Excludes Keyboard Users

Many routers rely on hover-based prefetching, but this approach completely excludes keyboard users since keyboard navigation never triggers hover events. This means keyboard users miss out on the performance benefits that mouse users get from hover-based prefetching.

The ForesightJS Solution

ForesightJS bridges the gap between wasteful viewport prefetching and basic hover prefetching. The ForesightManager predicts user interactions by analyzing mouse trajectory patterns, scroll direction and keyboard navigation sequences. This allows you to prefetch resources at the optimal time to improve performance, but targeted enough to avoid waste.

Basic Usage Example

This basic example is in vanilla JS, ofcourse most people will use ForesightJS with a framework. You can read about framework integrations in the docs.

import { ForesightManager } from "foresightjs"

// Register an element to be tracked
const myButton = document.getElementById("my-button")

// isTouchDevice can be used to change prefetch behaviour if the user is on a touch device
const { isTouchDevice } = ForesightManager.instance.register({
  element: myButton,
  callback: () => {
    // This is where your prefetching logic goes
  },
  hitSlop: 20, // Optional: "hit slop" in pixels. Overwrites defaultHitSlop
})

Integrations

Since ForesightJS is framework agnostic, it can be integrated with any JavaScript framework. While I haven't yet built integrations for every framework, ready-to-use implementations for Next.js and React Router are already available. Sharing integrations for other frameworks/packages is highly appreciated!

Configuration

ForesightJS can be used bare-bones but also can be configured. For all configuration possibilities you can reference the docs.

Development Tools

ForesightJS has dedicated Development Tools created with Foresight Events that help you understand and tune how foresight is working in your application. This standalone development package provides real-time visualization of mouse trajectory predictions, element bounds, and callback execution.

npm install js.foresight-devtools

import { ForesightDevtools } from "js.foresight-devtools"

// Initialize development tools
ForesightDevtools.initialize({
  showNameTags: true,
  sortElementList: "visibility",
})

This is particularly helpful when setting up ForesightJS for the first time or when fine-tuning for specific UI components.

What About Touch Devices and Slow Connections?

Since ForesightJS relies on the keyboard/mouse it will not register elements for touch devices. For limited connections (2G or data-saver mode), we respect the user's preference to minimize data usage and skip registration aswell.

The ForesightManager.instance.register() method returns these properties:

• isTouchDevice - true if user is on a touch device
• isLimitedConnection - true when user is on a 2G connection or has data-saver enabled
• isRegistered - true if element was actually registered

With these properties you could create your own fallback prefetching methods if required. For example if the user is on a touch device you could prefetch based on viewport. An example of this can be found in the Next.js or React Router ForesightLink components.

How Does ForesightJS Work?

For a detailed technical explanation of its prediction algorithms and internal architecture, see the Behind the Scenes documentation.

Providing Context to AI Tools

ForesightJS is a newer library, so most AI assistants and LLMs may not have much built-in knowledge about it. To improve their responses, you can provide the following context:

• Use llms.txt for a concise overview of the API and usage patterns.
• Use llms-full.txt for a full markdown version of the docs, ideal for AI tools that support context injection or uploads.
• All documentation pages are also available in markdown. You can view them by adding .md to the end of any URL, for example: https://foresightjs.com/docs/getting_started.md.

Contributing

Please see the contributing guidelines