coordinate-systems

name	coordinate-systems
description	Use when working with row or column indexes in Handsontable - translating between physical, visual, and renderable coordinates, using IndexMapper, or debugging index-related bugs where rows or columns appear in wrong positions

Coordinate Systems

Handsontable uses three coordinate systems because the position of a row or column can differ depending on whether you are looking at the raw data, the logical grid after filtering/trimming, or the actual DOM. Mixing them up is one of the most common sources of bugs.

The three systems

System	What it represents	Key behavior
Physical	Position in the source data array (0 to N)	Never changes regardless of filtering, sorting, trimming, hiding, or moving. Always 0 to N.
Visual	Position in what Handsontable has processed	Changes when data is filtered, sorted, trimmed, or columns/rows are moved. Hidden columns/rows still have visual indexes - hiding does not remove from visual space.
Renderable	Position in the DOM	Only matters for Walkontable. Very rarely used in public API and Handsontable.

The public Handsontable API mainly uses visual indexes, sometimes physical, and very rarely renderable (if any).

In Walkontable (the rendering engine), the data is already filtered, sorted, trimmed (etc.) by Handsontable, so Walkontable renders it as-is from 0 to N. Walkontable also uses "source index" and "render index" internally for virtualization - calculating what needs to be rendered at the current scroll position.

HidingMap vs TrimmingMap

• HidingMap - The index stays in the DataMap (visual space) but is not rendered in the DOM. Used by HiddenColumns and HiddenRows. Important: hidden columns/rows still have visual indexes. The data is still accessible via getDataAtCell() with visual coordinates.
• TrimmingMap - The index is removed from the DataMap entirely. Used by TrimRows and Filters. Trimmed rows do not exist in visual space at all.

IndexMapper API

Access via hot.rowIndexMapper or hot.columnIndexMapper. Key methods:

// Translate between systems
mapper.getPhysicalFromVisualIndex(visualIndex)
mapper.getVisualFromPhysicalIndex(physicalIndex)
mapper.getPhysicalFromRenderableIndex(renderableIndex)
mapper.getRenderableFromVisualIndex(visualIndex)

// Register a new map
mapper.createAndRegisterIndexMap(name, type, initialValue)
// type: 'hiding' | 'trimming'

When to use which coordinate

You are doing	Use
Reading or writing source data	Physical
Working with user-facing row/column positions, selection, or getDataAtCol()	Visual
Accessing DOM nodes, cell elements, or Walkontable APIs	Renderable
Storing persistent state (e.g., sorting order, filter conditions)	Physical

Common gotcha: Filters + ManualColumnMove

The conditionCollection and conditionUpdateObserver in the Filters plugin operate on physical indexes, while getDataAtCol() requires visual indexes. When manualColumnMove is active, physical and visual column order diverge. Always convert with getVisualFromPhysicalIndex() / getPhysicalFromVisualIndex() before crossing the boundary.

Quick plugin reference

Plugin	Map type	Coordinate it manages
HiddenColumns / HiddenRows	HidingMap	Visual to renderable
TrimRows / Filters	TrimmingMap	Physical to visual
ManualColumnMove / ColumnSorting	IndexesSequence	Physical to visual

Source files

Implementation lives in src/translations/ - see indexMapper.ts, maps/, and mapCollections/. For the deep subsystem reference (map types, translation methods, cache, observers, registration lifecycle), see handsontable/.ai/INDEX-MAPPING.md; for wider system context, handsontable/.ai/ARCHITECTURE.md.