Element Settings

When registering elements with the ForesightManager, you can provide configuration specific to each element. This allows you to fine-tune prediction behavior on a per-element basis.

Basic Element Registration

const myElement = document.getElementById("my-element")

const { isTouchDevice, isLimitedConnection, isRegistered } = ForesightManager.instance.register({
  element: myElement, // Required: The element to monitor
  callback: () => {
    // Required: Function that executes when interaction is predicted
    console.log("prefetching")
  },
  hitSlop: 50, // slop around the element, making its hitbox bigger
  name: "My Foresight button!", // name visible in the debug tools
  meta: {
    route: "/about",
  }, // your custom meta data for analytics
  reactivateAfter: 5 * 60 * 1000, // time for the element to reactivate after the callback has been hit
})

Registration Parameters

TypeScript Type: ForesightRegisterOptions or ForesightRegisterOptionsWithoutElement if you want to omit the element

Required Parameters

element

• Type: element | NodeListOf<element>
• Required: Yes
• Description: The DOM element (or a NodeList of elements) to monitor for user interactions. When a NodeList is passed, all elements are registered with the same callback and settings.

// Single element
const button = document.querySelector("#my-button")

ForesightManager.instance.register({
  element: button,
  callback: () => {
    /* prefetch logic */
  },
})

// Multiple elements via NodeList
const navLinks = document.querySelectorAll("nav a")

ForesightManager.instance.register({
  element: navLinks,
  callback: elementData => {
    /* elementData identifies which element triggered */
  },
})

---

callback

• Type: (elementData: ForesightElementData) => void
• Required: Yes
• Description: Function that executes when interaction is predicted or occurs. This is where your prefetching logic goes. The callback receives the ForesightElementData of the element that triggered it, which is especially useful when registering multiple elements with a shared callback.
• Note: If you await your prefetch logic the callbackCompleted event will show you how long your prefetch took to run.

ForesightManager.instance.register({
  element: myElement,
  callback: elementData => {
    console.log(`Triggered ${elementData.element}`)
    // prefetch logic
  },
})

---

Optional Parameters

hitSlop

• Type: number | Rect
• Required: No
• Default: Uses defaultHitSlop from global settings (which is 0 if not set)
• Description: Fully invisible "slop" around the element that increases the hover hitbox.

// Uniform hit slop (20px on all sides)
ForesightManager.instance.register({
  element: myElement,
  callback: () => {},
  hitSlop: 20,
})

// Custom hit slop for each side
ForesightManager.instance.register({
  element: myElement,
  callback: () => {},
  hitSlop: {
    top: 10,
    left: 50,
    right: 50,
    bottom: 100,
  },
})

---

name

• Type: string
• Required: No
• Default: element.id or "unnamed" if no id
• Description: A descriptive name for the element, useful for development tools and debugging.

ForesightManager.instance.register({
  element: myElement,
  callback: () => {
    /* logic */
  },
  name: "Product Navigation Button", // Helpful for debugging
})

---

reactivateAfter

• Type: number
• Required: No
• Default: Infinity
• Description: Time in milliseconds after which the callback can be fired again. Set to Infinity to prevent callback from firing again after first execution.
• Note: Even though ForesightJS doesn't store any data, you can set this to the same time as your data would become stale normally. In most cases you can just leave this on the default value, as it will get reset on page refresh/rerouting anyways.

ForesightManager.instance.register({
  element: myElement,
  callback: () => {},
  reactivateAfter: 5 * 60 * 1000, // 5 minutes
})

---

meta

• Type: Record<string, unknown>
• Required: No
• Default: {}
• Description: Stores additional information about the registered element. Visible in all element-related events and in the devtools.

ForesightManager.instance.register({
  element: productLink,
  callback: () => {},
  meta: {
    route: "/about",
    section: "main",
    category: "content",
  },
})

Registration Return Value

The register() method returns useful information about the registration. When a single element is passed, it returns a ForesightRegisterResult. When a NodeList is passed, it returns ForesightRegisterResult[].

TypeScript Type: ForesightRegisterResult or ForesightRegisterResult[]

// Single element returns ForesightRegisterResult
const { isTouchDevice, isLimitedConnection, isRegistered } = ForesightManager.instance.register({
  element: myElement,
  callback: () => {},
})

// NodeList returns ForesightRegisterResult[]
const results = ForesightManager.instance.register({
  element: document.querySelectorAll(".my-elements"),
  callback: () => {},
})

---

Return Properties

isTouchDevice

• Type: boolean
• Description: Indicates whether the current device is a touch device.

Deprecated

As of v3.3, ForesightJS handles touch devices internally with dedicated touch strategies. You no longer need to check this value for fallback prefetching logic.

---

isLimitedConnection

• Type: boolean
• Description: Is true when the user's connection is slower than the configured minimumConnectionType setting (defaults to "3g") or data saver is enabled. The element is still registered, but stays inactive (it is excluded from prediction and never fires its callback), so no data is consumed. See Global Settings for details.
• Note: This feature relies on the Network Information API which is not supported in all major browsers. When the API is not available, ForesightJS treats the connection as unlimited.

---

isRegistered

• Type: boolean
• Description: Is true once the element is registered with the manager, independent of connection. It only becomes false after the element is unregistered manually. Detaching the 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. On a limited connection the element is likewise registered but inactive, so use isLimitedConnection / isActive to detect inactivity, not isRegistered.