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"

// Initialize the manager if you want custom global settings (do this once at app startup)
// If you dont want global settings, you dont have to initialize the manager
ForesightManager.initialize({
  debug: false, // Set to true to see visualization
  trajectoryPredictionTime: 80, // How far ahead (in milliseconds) to predict the mouse trajectory
})

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

const { isTouchDevice, unregister } = ForesightManager.instance.register({
  element: myButton,
  callback: () => {
    // This is where your prefetching logic goes
  },
  hitSlop: 20, // Optional: "hit slop" in pixels. Overwrites defaultHitSlop
})

// Later, when done with this element:
unregister()

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.

Debugging Visualization

ForesightJS includes a Visual Debugging system that helps you understand and tune how foresight is working in your application. 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

Since ForesightJS is a relatively new and unknown library, most AI assistants and large language models (LLMs) may not have comprehensive knowledge about it in their training data. To help AI assistants better understand and work with ForesightJS, you can provide them with context from our llms.txt page, which contains structured information about the library's API and usage patterns.

Additionally, every page in our documentation is available in markdown format (try adding .md to any documentation URL). You can share these markdown files as context with AI assistants, though all this information is also consolidated in the llms.txt file for convenience.

Future of ForesightJS

ForesightJS will continue to evolve with a focus on staying as lightweight and performant as possible. To achieve this the plan is to decouple the debugger and make it its own standalone dev package, reducing the core library size even further.

Beyond size optimization, performance remains central to every development decision. Each release will focus on improving prediction accuracy while reducing computational overhead, ensuring ForesightJS stays practical for production environments. We also want to move as much processing as possible off the main thread to keep user interfaces responsive.

These performance improvements go hand in hand with expanding accessibility across different development environments. The documentation will grow to include more framework integrations beyond the current Next.js and React Router implementations, making ForesightJS accessible to developers working with different technology stacks and routing solutions.

All of these efforts benefit from community input. contributing guidelines are always welcome, whether for new framework integrations, performance improvements, or feature ideas.

Contributing

Please see the contributing guidelines