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
| Address | Meaning | Where you meet it |
|---|---|---|
| Data index | The position in your data array. | The second argument of getRowId. |
| View index | The 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 id | The 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
dataarray. - 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
onActiveCellChangehand out both addresses.ViewCellRefholds the row id, the column id, and the view position at the time of the event. - Cell actions take a
CellRef. Each has an*Atvariant, such asselectCellAt, that takes aViewCoord. - 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
useDataGridViewStalereturnstrue.actions.reconcileView()rebuilds the view. See Stream updates.
Read an address
Inside a DataGridProvider, these hooks convert between the addresses:
useDataGridViewIndex()returns theviewIndexarray.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.useDataGridRowIdreturns an index-derived placeholder id for it, anduseDataGridRowreturnsundefined. 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.