# VirtualState

> _Since v0.1.1_

Virtual window bookkeeping; modified in-place as scroll position changes.

Tracks virtualization state for row rendering. The grid only renders
rows within the visible viewport window (start to end) plus overscan.

#### Example

```typescript
import type { VirtualState, InternalGrid } from '@toolbox-web/grid';

class MyPlugin extends BaseGridPlugin {
  logVirtualWindow(): void {
    const grid = this.grid as InternalGrid;
    const vs = grid.virtualization;

    console.log(`Row height: ${vs.rowHeight}px`);
    console.log(`Visible rows: ${vs.start} to ${vs.end}`);
    console.log(`Virtualization: ${vs.enabled ? 'on' : 'off'}`);
  }
}
```

## Properties

| Property | Type | Description |
| -------- | ---- | ----------- |
| `enabled` | <code>boolean</code> |  |
| `rowHeight` | <code>number</code> |  |
| `bypassThreshold` | <code>number</code> | Threshold for bypassing virtualization (renders all rows if totalRows &lt;= bypassThreshold) |
| `start` | <code>number</code> |  |
| `end` | <code>number</code> |  |
| `container` | <code>HTMLElement &#124; unknown</code> | Faux scrollbar element that provides scroll events (AG Grid pattern) |
| `viewportEl` | <code>HTMLElement &#124; unknown</code> | Rows viewport element for measuring visible area height |
| `totalHeightEl` | <code>HTMLElement &#124; unknown</code> | Spacer element inside faux scrollbar for setting virtual height |
| `positionCache` | <code>RowPosition[] &#124; unknown</code> | Position cache for variable row heights. Index-based array mapping row index → \{offset, height, measured\}. Rebuilt when row count changes (expand/collapse, filter). `null` when using uniform row heights (default). |
| `heightCache` | <code>object</code> | Height cache by row identity. Persists row heights across position cache rebuilds. Uses dual storage: Map for string keys (rowId, __rowCacheKey) and WeakMap for object refs. |
| `averageHeight` | <code>number</code> | Running average of measured row heights. Used for estimating unmeasured rows. |
| `measuredCount` | <code>number</code> | Number of rows that have been measured. |
| `variableHeights` | <code>boolean</code> | Whether variable row height mode is active (rowHeight is a function). |
| `cachedViewportHeight` | <code>number</code> | Cached viewport element height. Updated by ResizeObserver and force-refresh only. |
| `cachedFauxHeight` | <code>number</code> | Cached faux scrollbar element height. Updated alongside viewport height. |
| `cachedScrollAreaHeight` | <code>number</code> | Cached scroll-area element height. Updated alongside viewport/faux heights. |
| `scrollAreaEl` | <code>HTMLElement &#124; unknown</code> | Cached reference to .tbw-scroll-area element. Set during scroll listener setup. |
| `scrollMapping` | <code><a href="/grid/api/plugin-development/interfaces/scrollmapping/">ScrollMapping</a></code> | Active scroll mapping between native `scrollTop` (clamped spacer space) and "virtual" row-content space. Identity (`capped: false`) for datasets within the browser's max-element-height cap (Chromium ~33.5M px). For larger datasets, the spacer height is clamped and `scrollTop` must be translated via this mapping before computing the visible window. Updated by `calculateTotalSpacerHeight`. <span class="since-badge" title="Introduced in v2.13.0">v2.13.0+</span> |

### Property Details

#### scrollMapping

**See also:** [`computeScrollMapping`](/grid/api/plugin-development/functions/computescrollmapping.md)

---

## See Also

- [`GridConfig.rowHeight`](/grid/api/core/interfaces/gridconfig.md#rowheight) for configuring row height