VirtualState

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

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	boolean
rowHeight	number
bypassThreshold	number	Threshold for bypassing virtualization (renders all rows if totalRows <= bypassThreshold)
start	number
end	number
container	HTMLElement | unknown	Faux scrollbar element that provides scroll events (AG Grid pattern)
viewportEl	HTMLElement | unknown	Rows viewport element for measuring visible area height
totalHeightEl	HTMLElement | unknown	Spacer element inside faux scrollbar for setting virtual height
positionCache	RowPosition[] | unknown	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	object	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	number	Running average of measured row heights. Used for estimating unmeasured rows.
measuredCount	number	Number of rows that have been measured.
variableHeights	boolean	Whether variable row height mode is active (rowHeight is a function).
cachedViewportHeight	number	Cached viewport element height. Updated by ResizeObserver and force-refresh only.
cachedFauxHeight	number	Cached faux scrollbar element height. Updated alongside viewport height.
cachedScrollAreaHeight	number	Cached scroll-area element height. Updated alongside viewport/faux heights.
scrollAreaEl	HTMLElement | unknown	Cached reference to .tbw-scroll-area element. Set during scroll listener setup.

See Also

• GridConfig.rowHeight for configuring row height