菜单
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
| 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 |
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.
| 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.
HiddenColumns and HiddenRows. Important: hidden columns/rows still have visual indexes. The data is still accessible via getDataAtCell() with visual coordinates.TrimRows and Filters. Trimmed rows do not exist in visual space at all.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'
| 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 |
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.
| Plugin | Map type | Coordinate it manages |
|---|---|---|
HiddenColumns / HiddenRows | HidingMap | Visual to renderable |
TrimRows / Filters | TrimmingMap | Physical to visual |
ManualColumnMove / ColumnSorting | IndexesSequence | Physical to visual |
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.
Use for ANY work touching the `handsontable/` core package: fixing bugs, adding features, modifying TypeScript types, removing as-casts, writing or debugging plugins, editors, renderers, validators, cell types, hooks, shortcuts, selection, helpers, index translations, or i18n. Also use for how-to questions about core internals (plugin lifecycle, coordinate systems, hook registration, TypeScript conventions). Triggers on file paths under `handsontable/src/` (excluding `3rdparty/walkontable/` which has its own skill), or when the user describes a symptom in the core grid without naming a file. This is the primary entry point for all core Handsontable development — when in doubt, load it.
Use when creating code examples for documentation pages - JavaScript, TypeScript, React, Angular, and Vue variants with proper imports, registration, and license key
Use the pre-built code-review-graph knowledge graph for ANY cross-file task in this monorepo — exploring code, debugging symptom→root-cause, planning a safe refactor/rename, or reviewing a branch/PR. Reach for this BEFORE manual Grep+Read of call chains; results are 2-6x cheaper. Trigger on "who calls X", "what imports Y", "where is X used", "dependency chain", "blast radius", "trace this bug", "rename X across the codebase", "find dead code", "what would break if I change", "review this PR" — or any question that spans multiple files, even when Grep seems enough.
Use when creating standalone examples in examples/next/docs/ for visual regression testing or documentation demos - covers the Vite-based example structure, sample data patterns, and multi-feature demonstration
Use when creating or modifying a Handsontable cell type that composes an editor, renderer, and validator into a reusable configuration object registered by name
Use when reviewing changed or staged code, a branch, or a PR in the Handsontable monorepo across architecture, code quality, performance, and accessibility. Covers SOLID / Law of Demeter / plugin decoupling / breaking-changes policy, custom ESLint rules / JSDoc / naming / cognitive complexity, large-array and render-batching performance, and WCAG 2.1 AA + keyboard navigation. Trigger when asked to review changes, check a diff against Handsontable conventions, assess architectural correctness, spot performance regressions, or verify accessibility — and as the design lens before or while implementing any core change.