gridcn2.0.0
Concepts

State and view index

Learn how the grid addresses rows and columns by data index, view index, and id, which APIs take which address, and why a view index goes stale.

A row has three addresses, and the grid APIs mix them. A call that takes the wrong one acts on another record after a sort. This page names the addresses and says which one each API takes.

Three addresses

AddressMeaningWhere you meet it
Data indexThe position in your data array.The second argument of getRowId.
View indexThe position in the sorted and filtered list that the user sees. On a paged grid, the position on the shown page.ViewCoord, insertRow, insertRows, and the At actions deleteRowsAt, duplicateRowsAt, and setRowCheckedAt. The At actions take view row numbers. viewIndex(n) and viewIndexes([…]) brand them.
Row idThe stable id that getRowId returns.CellRef, deleteRows, duplicateRows, setRowChecked, and the operations of a DataChange.

Data grid props covers the default of getRowId.

This sample deletes a row by id and a row by view index. After a sort, the view index names another record than before, and the id names the same record:

import {
  useDataGridActions,
  viewIndexes,
} from "@/components/data-grid/data-grid";

export function DeleteButtons() {
  const actions = useDataGridActions();
  return (
    <>
      <button onClick={() => actions.deleteRows(["order-7"])}>
        Delete order 7
      </button>
      <button onClick={() => actions.deleteRowsAt(viewIndexes([0]))}>
        Delete top row
      </button>
    </>
  );
}

A column has the same split. A column id names the column for good. The column part of a ViewCoord counts the visible columns in display order, without the row marker column.

What rebuilds the view

The grid keeps a viewIndex array. Its entry at a view index is the data index of the row shown there. These changes rebuild it:

  • With sortMode="client", a sort.
  • With filterMode="client", a filter.
  • A new data array.
  • An inserted, duplicated, or deleted row.
  • A call to actions.reconcileView().
  • A page or page-size change of a paged grid.

A mode set to "server" skips its own step, because your backend applies the sort or the filter. A search never narrows the view. It highlights matches and moves between them.

A rebuild changes the view index of rows. It never changes a row id.

Which address to keep

A view index is valid for the render that read it. Keep a row id or a CellRef for anything that outlives a render.

  • The active cell and the selection sit in the store as view indexes. After a rebuild, the grid moves them back onto their records. Selection model lists the rules.
  • Cell events such as onActiveCellChange hand out both addresses. ViewCellRef holds the row id, the column id, and the view position at the time of the event.
  • Cell actions take a CellRef. Each has an *At variant, such as selectCellAt, that takes a ViewCoord.
  • An edit, paste, fill, or cell clear can write a column that the active sort or filter reads. The rows then keep their old view index, and useDataGridViewStale returns true. actions.reconcileView() rebuilds the view. See Stream updates.

Read an address

Inside a DataGridProvider, these hooks convert between the addresses:

  • useDataGridViewIndex() returns the viewIndex array.
  • useDataGridRowId(viewRowIndex) returns the row id at a view index.
  • useDataGridRowIdToViewRow() returns a map from row id to view index.
  • useDataGridRow(viewRowIndex) returns the row object.

Store hooks describes each hook.

Rows without an index

  • A row that scroll mode has not loaded yet is a hole in data. useDataGridRowId returns an index-derived placeholder id for it, and useDataGridRow returns undefined. The placeholder stays valid only while the hole keeps its data index.
  • The rows of a plugin band belong to the plugin. They have no data index and no view index. See Plugin overlays.

On this page