Global Settings

Global settings apply to all registered elements and are configured once via ForesightManager.initialize() at your app's entry point. Import ForesightManager from @foresightjs/react.

tip

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

Basic Configuration

// 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",
  enableManagerLogging: false,
  minimumConnectionType: "3g",
})

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 Settings

touchDeviceStrategy

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

ForesightManager.initialize({
  touchDeviceStrategy: "viewport",
})

---

Minimum Connection Settings

minimumConnectionType

• Type: MinimumConnectionType
• Default: "3g"
• Options: "slow-2g", "2g", "3g", "4g"
• Description: The minimum connection speed required for prefetching. When the user's connection is slower than this threshold (or data saver is enabled), elements are still registered but stay inactive: they are excluded from prediction and never fire their callback.
• 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.

ForesightManager.initialize({
  minimumConnectionType: "3g",
})

---

Other Settings

enableManagerLogging

• Type: boolean
• Default: false
• Description: Logs basic information about the ForesightManager and its handlers that is not available through events. Mostly used by the maintainers of ForesightJS to debug the manager, but might be useful for implementers aswell.
• Note: Examples of logs are: Initializing the manager, switching from device strategy (e.g. Mouse to pen), aborting controllers and invalidating cache.

ForesightManager.initialize({
  enableManagerLogging: true,
})

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, js.foresight-devtools. See the development tools page in the debugging section for details on installing and configuring it.

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