Skip to main content
Version: 3.3

Global Settings

Global settings are specified when initializing the ForesightManager and apply to all registered elements. This should be done once at your application's entry point.

tip

If you want the default global options you don't need to initialize the ForesightManager explicitly.

Basic Configuration​

import { ForesightManager } from "js.foresight"

// Initialize the manager once at the top of your app if you want custom global settings
// ALL SETTINGS ARE OPTIONAL
ForesightManager.initialize({
  enableMousePrediction: true,
  positionHistorySize: 8,
  trajectoryPredictionTime: 80,
  defaultHitSlop: 10,
  enableTabPrediction: true,
  tabOffset: 3,
  enableScrollPrediction: true,
  scrollMargin: 150,
  touchDeviceStrategy: "viewport",
})

Available Settings​

TypeScript Type: ForesightManagerSettings

note

All numeric settings are clamped to their specified Min/Max values to prevent invalid configurations.

Mouse Prediction Settings​

enableMousePrediction​

  • Type: boolean
  • Default: true
  • Description: Toggles whether trajectory prediction is active. If false, only direct hovers will trigger the callback for mouse users.
  • Note: When this is turned off ForesightJS will still trigger callbacks while hovering over the element's extended range (rect + hitslop)
ForesightManager.initialize({
  enableMousePrediction: false, // Disable trajectory prediction
})

positionHistorySize​

  • Type: number
  • Default: 8
  • Clamped between: 2-30
  • Description: Number of mouse positions to keep in history for velocity calculations. Higher values provide smoother predictions but use more memory.
ForesightManager.initialize({
  positionHistorySize: 12, // Keep more position history for smoother predictions
})

trajectoryPredictionTime​

  • Type: number
  • Default: 120
  • Clamped between: 10-200 milliseconds
  • Description: How far ahead (in milliseconds) to predict the mouse trajectory. Larger values trigger callbacks sooner but may reduce accuracy.
ForesightManager.initialize({
  trajectoryPredictionTime: 100, // Predict 100ms into the future
})

Keyboard Prediction Settings​

enableTabPrediction​

  • Type: boolean
  • Default: true
  • Description: Toggles whether keyboard prediction is active for tab navigation.
ForesightManager.initialize({
  enableTabPrediction: false, // Disable keyboard prediction
})

tabOffset​

  • Type: number
  • Default: 2
  • Clamped between: 0-20
  • Description: Number of tab stops away from an element to trigger its callback. Only works when enableTabPrediction is true.
ForesightManager.initialize({
  tabOffset: 1, // Trigger callback when 1 tab stop away
})

Scroll Prediction Settings​

enableScrollPrediction​

  • Type: boolean
  • Default: true
  • Description: Toggles whether scroll prediction is active.
ForesightManager.initialize({
  enableScrollPrediction: false, // Disable scroll prediction
})

scrollMargin​

  • Type: number
  • Default: 150
  • Clamped between: 30-300 pixels
  • Description: Sets the pixel distance to check from the mouse position in the scroll direction for triggering callbacks.
ForesightManager.initialize({
  scrollMargin: 200, // Check 200px ahead in scroll direction
})

Hit Slop Settings​

defaultHitSlop​

  • Type: number | Rect
  • Default: {top: 0, left: 0, right: 0, bottom: 0}
  • Clamped between: 0-2000 pixels (per side)
  • Description: Default fully invisible "slop" around elements for all registered elements. Basically increases the hover hitbox.
  • Note: This can be overwritten on an element basis by setting its hitslop.
// Uniform hit slop
ForesightManager.initialize({
  defaultHitSlop: 20, // 20px on all sides
})

// Custom hit slop for each side
ForesightManager.initialize({
  defaultHitSlop: {
    top: 10,
    left: 20,
    right: 20,
    bottom: 15,
  },
})

Touch Device Strategy (v3.3.0+)​

touchDeviceStrategy​

  • Type: TouchDeviceStrategy
  • Default: "onTouchStart"
  • Options: "none", "viewport", "onTouchStart"
  • Description: Strategy to use for touch devices (mobile / pen users).
ForesightManager.initialize({
  touchDeviceStrategy: "viewport",
})

Available strategies:

  • "onTouchStart" - Captures the initial touch event to begin prefetching when users start interacting with registered elements
  • "viewport" - Detects when registered elements enter the viewport and prefetches their content based on visibility
  • "none" - Disables ForesightJS on touch devices

Runtime Configuration Changes​

You can update global settings at runtime using alterGlobalSettings(). This is not adviced for regular use and is mainly used for developers creating tools on top of Foresight. For regular use, you should set global settings during initialization with ForesightManager.initialize().

// Change settings after initialization
ForesightManager.instance.alterGlobalSettings({
  trajectoryPredictionTime: 100,
  enableScrollPrediction: false,
})

This is particularly useful when integrating with development tools or when you need to adjust settings based on user preferences or device capabilities.

Development Tools Integration​

Development Tools

Visual development tools are available as a separate package. See the development tools documentation for details on installing and configuring the js.foresight-devtools package.

The development tools provide a real-time interface for adjusting these global settings and seeing their immediate effects on prediction behavior.