Skip to main content
Version: 4.x

Events

ForesightManager emits events for element registration, prediction, and callback execution. The ForesightJS DevTools use them for visual debugging, and you can listen to them yourself for telemetry, analytics, or counters.

Usage​

In React the easiest way to listen to events is the useForesightEvent hook, which adds and removes the listener for you:

import { useState } from "react"
import { useForesightEvent } from "@foresightjs/react"

function PrefetchCounter() {
  const [hits, setHits] = useState(0)

  useForesightEvent("callbackInvoked", event => {
    setHits(count => count + 1)
  })

  return <p>{hits} prefetches triggered</p>
}

The standard ForesightManager.instance.addEventListener / removeEventListener pattern is also available if you want to listen outside of a component.

Available Events​

Interaction Events​

Events fired when user interactions trigger callbacks.

callbackInvoked​

Fired before an element's callback is executed

type CallbackInvokedEvent = {
  type: "callbackInvoked"
  timestamp: number
  element: ForesightElement
  state: ForesightElementState
  hitType: CallbackHitType
}

Related Types: CallbackHitType • ForesightElementState

callbackCompleted​

Fired after an element's callback is executed

type CallbackCompletedEvent = {
  type: "callbackCompleted"
  timestamp: number
  element: ForesightElement
  state: ForesightElementState
  hitType: CallbackHitType
  elapsed: number // Time between callbackInvoked and callbackCompleted
  status: "success" | "error" | undefined
  errorMessage: string | null
  wasLastActiveElement: boolean
}

Related Types: CallbackHitType • ForesightElementState

Element Lifecycle Events​

Events fired during element registration, updates, and cleanup.

elementRegistered​

Fired when a new element is registered with ForesightManager using ForesightManager.instance.register({ element, callback }). Registering an already-tracked element updates its options without emitting another elementRegistered event.

type ElementRegisteredEvent = {
  type: "elementRegistered"
  timestamp: number
  element: ForesightElement
  state: ForesightElementState
}

Related Types: ForesightElementState

elementUnregistered​

Fired when an element is removed from ForesightManager's tracking via ForesightManager.instance.unregister(element). Detaching an element from the DOM no longer unregisters it. It is parked (kept registered but inactive) and resumed on reattach, so no elementUnregistered event fires for that. The "disconnected" reason is therefore no longer emitted.

type ElementUnregisteredEvent = {
  type: "elementUnregistered"
  timestamp: number
  element: ForesightElement
  state: ForesightElementState
  unregisterReason: "disconnected" | "apiCall" | "devtools" | (string & {})
  wasLastRegisteredElement: boolean
}

Related Types: ForesightElementState

Prediction Events​

Events fired during movement prediction calculations.

mouseTrajectoryUpdate​

Fired during mouse movement for trajectory calculations

type MouseTrajectoryUpdateEvent = {
  type: "mouseTrajectoryUpdate"
  trajectoryPositions: {
    positions: CircularBuffer<MousePosition> // mouse position history
    currentPoint: { x: number; y: number }
    predictedPoint: { x: number; y: number }
  }
  predictionEnabled: boolean
}

scrollTrajectoryUpdate​

Fired during scroll events when scroll prediction is active

type ScrollTrajectoryUpdateEvent = {
  type: "scrollTrajectoryUpdate"
  currentPoint: Point // { x: number; y: number }
  predictedPoint: Point // { x: number; y: number }
  scrollDirection: ScrollDirection // "down" | "up" | "left" | "right"
}

Configuration Events​

Events fired when ForesightManager configuration changes.

managerSettingsChanged​

Fired when global ForesightManager settings are updated via the devtools or via ForesightManager.instance.alterGlobalSettings().

type ManagerSettingsChangedEvent = {
  type: "managerSettingsChanged"
  timestamp: number
  managerData: Readonly<ForesightManagerData>
  updatedSettings: UpdatedManagerSetting[]
}

Related Types: ForesightManagerData

deviceStrategyChanged​

Fired when user switches between input methods (mouse, touch, or pen).

type DeviceStrategyChangedEvent = {
  type: "deviceStrategyChanged"
  timestamp: number
  newStrategy: CurrentDeviceStrategy // "mouse" | "touch" | "pen"
  oldStrategy: CurrentDeviceStrategy // "mouse" | "touch" | "pen"
}