# Global Settings

Global settings apply to all registered elements and are configured once via `ForesightManager.initialize()` in your `main.ts`. Import `ForesightManager` from `@foresightjs/vue`.

tip

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

## Basic Configuration[​](#basic-configuration "Direct link to 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",
  setDataAttributes: true,
})
```

## Available Settings[​](#available-settings "Direct link to Available Settings")

**TypeScript Type:** `ForesightManagerSettings`

note

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

### Mouse Prediction Settings[​](#mouse-prediction-settings "Direct link to Mouse Prediction Settings")

#### `enableMousePrediction`[​](#enablemouseprediction "Direct link to 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`[​](#positionhistorysize "Direct link to 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`[​](#trajectorypredictiontime "Direct link to 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[​](#keyboard-prediction-settings "Direct link to Keyboard Prediction Settings")

#### `enableTabPrediction`[​](#enabletabprediction "Direct link to enabletabprediction")

* **Type:** `boolean`
* **Default:** `true`
* **Description:** Toggles whether keyboard prediction is active for tab navigation.

```
ForesightManager.initialize({
  enableTabPrediction: false, // Disable keyboard prediction
})
```

***

#### `tabOffset`[​](#taboffset "Direct link to 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[​](#scroll-prediction-settings "Direct link to Scroll Prediction Settings")

#### `enableScrollPrediction`[​](#enablescrollprediction "Direct link to enablescrollprediction")

* **Type:** `boolean`
* **Default:** `true`
* **Description:** Toggles whether scroll prediction is active.

```
ForesightManager.initialize({
  enableScrollPrediction: false, // Disable scroll prediction
})
```

***

#### `scrollMargin`[​](#scrollmargin "Direct link to 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[​](#hit-slop-settings "Direct link to Hit Slop Settings")

#### `defaultHitSlop`[​](#defaulthitslop "Direct link to 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 overridden per element 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[​](#touch-device-settings "Direct link to Touch Device Settings")

#### `touchDeviceStrategy`[​](#touchdevicestrategy "Direct link to 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[​](#minimum-connection-settings "Direct link to Minimum Connection Settings")

#### `minimumConnectionType`[​](#minimumconnectiontype "Direct link to 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](https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation) 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[​](#other-settings "Direct link to Other Settings")

#### `enableManagerLogging`[​](#enablemanagerlogging "Direct link to 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,
})
```

***

### Data Attribute Settings[​](#data-attribute-settings "Direct link to Data Attribute Settings")

#### `setDataAttributes`[​](#setdataattributes "Direct link to setdataattributes")

* **Type:** `boolean`

* **Default:** `true`

* **Description:** When `true`, the manager mirrors every registered element's prediction state onto `data-*` attributes via direct DOM mutation, so plain CSS can style predictions without any framework re-render. The attributes are kept in sync on every state change and removed when an element unregisters. Toggling this at runtime applies or removes the attributes on all currently-registered elements.

  <!-- -->

  * `data-predicted` — present while `isPredicted` is `true`
  * `data-active` — present while `isActive` is `true` (eligible to fire)
  * `data-callback-running` — present while `isCallbackRunning` is `true`
  * `data-status` — set to `"success"` or `"error"` once a callback completes

```
ForesightManager.initialize({
  setDataAttributes: false, // Opt out of data-* mirroring
})
```

```
[data-predicted] {
  outline: 2px solid orange;
}
```

## Runtime Configuration Changes[​](#runtime-configuration-changes "Direct link to Runtime Configuration Changes")

You can update global settings at runtime using `alterGlobalSettings()`. This is mainly for developers building tools on top of `Foresight`. For regular use, set your global settings once during initialization with `ForesightManager.initialize()`.

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

## Development Tools Integration[​](#development-tools-integration "Direct link to 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.