Static Properties

The hooks handle registering and unregistering for you; the properties below are escape hatches for debugging and inspecting the manager state.

import { ForesightManager } from "@foresightjs/react"

The ForesightManager exposes several static properties for accessing and checking the manager state.

All properties are read-only

ForesightManager.instance

Gets the singleton instance of ForesightManager, initializing it if necessary. This is the primary way to access the manager throughout your application.

Returns: ForesightManager

Example:

const manager = ForesightManager.instance

// Register a single element
manager.register({
  element: myButton,
  callback: () => console.log("Predicted interaction!"),
})

// Register multiple elements via NodeList
const navLinks = document.querySelectorAll("nav a")
manager.register({
  element: navLinks,
  callback: state => console.log(`Predicted: ${state.name}`),
})

ForesightManager.instance.registeredElements

Gets a Map of all currently registered elements and their associated ForesightElementState. This is useful for debugging or inspecting the current state of registered elements.

Returns: ReadonlyMap<ForesightElement, ForesightElementState>

ForesightManager.instance.isInitiated

Checks whether the ForesightManager has been initialized.

Returns: Readonly<boolean>

ForesightManager.instance.reactivate(element)

Manually reactivates an element (or all elements in a NodeList), allowing its callback to be triggered again. This is useful when you want to re-enable prefetching for an element before its reactivateAfter timeout expires.

Parameters:

• element - The DOM element or NodeList to reactivate

Example:

// Single element
const myButton = document.getElementById("my-button")
ForesightManager.instance.reactivate(myButton)

// Multiple elements
const navLinks = document.querySelectorAll("nav a")
ForesightManager.instance.reactivate(navLinks)

ForesightManager.instance.unregister(element, reason?)

Removes an element (or all elements in a NodeList) from ForesightManager's tracking.

Frameworks handle this for you

The official React and Vue integrations call unregister automatically when a component unmounts, so you rarely call it yourself there.

Detaching an element from the DOM does not unregister it. It is parked (kept registered but inactive) and resumes when it reattaches, so it survives detach/reattach and re-parenting. Unregistering only happens when you call this method explicitly.

If you register elements yourself (vanilla JS) and permanently remove one from the DOM, call unregister to stop tracking it. Otherwise it stays parked and keeps a reference to the detached element, which prevents it from being garbage collected.

Parameters:

• element - The DOM element or NodeList to unregister
• reason (optional) - A string describing why the element was unregistered (useful for debugging via events)

Example:

// Single element
const myButton = document.getElementById("my-button")
ForesightManager.instance.unregister(myButton, "user-navigation")

// Multiple elements
const navLinks = document.querySelectorAll("nav a")
ForesightManager.instance.unregister(navLinks)

ForesightManager.instance.getManagerData

Snapshot of the current ForesightManager state, including all global settings, registered elements, position observer data, and interaction statistics. This is primarily used for debugging, monitoring, and development purposes.

Properties:

• registeredElements - Map of all currently registered elements and their associated ForesightElementState
• eventListeners - Map of all event listeners listening to ForesightManager events.
• globalSettings - Current global configuration settings
• globalCallbackHits - Total callback execution counts by interaction type (mouse/tab/scroll/viewport/touch) and by subtype (hover/trajctory for mouse, forwards/reverse for tab, direction for scroll)
• currentDeviceStrategy - Which strategy is being used. Can be either touch or mouse, this changes dynamically
• activeElementCount - Amount of elements currently active (not the same as registered)
• parkedElementCount - Amount of elements currently parked: detached from the DOM (isParked: true) and waiting to reconnect
• loadedModules - Shows which handlers and predictors have been lazy loaded

Returns: Readonly<ForesightManagerData>

The return will look something like this:

{
  "registeredElements": {
    "size": 7,
    "entries": "<all your currently registered elements>"
  },
  "activeElementCount": 5,
  "parkedElementCount": 0,
  "currentDeviceStrategy": "mouse",
  "eventListeners": {
    "0": {
      "elementRegistered": []
    },
    "1": {
      "elementUnregistered": []
    },
    "2": {
      "mouseTrajectoryUpdate": []
    },
    "3": {
      "scrollTrajectoryUpdate": []
    },
    "4": {
      "managerSettingsChanged": []
    },
    "5": {
      "callbackInvoked": []
    },
    "6": {
      "callbackCompleted": []
    }
  },
  "globalSettings": {
    "defaultHitSlop": {
      "bottom": 10,
      "left": 10,
      "right": 10,
      "top": 10
    },
    "enableMousePrediction": true,
    "enableScrollPrediction": true,
    "enableTabPrediction": true,
    "positionHistorySize": 10,
    "scrollMargin": 150,
    "tabOffset": 2,
    "trajectoryPredictionTime": 100
  },
  "globalCallbackHits": {
    "mouse": {
      "hover": 0,
      "trajectory": 3
    },
    "scroll": {
      "down": 2,
      "left": 0,
      "right": 0,
      "up": 0
    },
    "tab": {
      "forwards": 3,
      "reverse": 0
    },
    "touch": 0,
    "viewport": 0,
    "total": 8
  },
  "loadedModules": {
    "desktopHandler": true,
    "touchHandler": false,
    "predictors": {
      "mouse": true,
      "tab": true,
      "scroll": true,
      "viewport": false,
      "touchStart": false
    }
  }
}