Row identity
Give each row of Handsontable DataGrid an id that stays with the row’s record, and find rows by their ids.
Overview
Handsontable addresses rows by index. A visual index changes when you sort, filter, or move rows, and a physical index changes when you insert or remove rows. Neither identifies a record over time.
A row id does. It stays with the row’s record when you:
- Sort rows.
- Filter rows.
- Move rows.
- Trim rows.
- Insert or remove other rows.
- Undo or redo any of those actions.
Use row ids when you save edits to a backend keyed by record, apply the result of an asynchronous request to the record it was made for, or keep any state that must follow a record rather than a position.
Enable row ids
Set the rowId option at the grid level. It accepts one of the following:
| Setting | Description |
|---|---|
| A string | The property that holds the id in each row object. A property named exactly as the string wins, even when the name contains a dot. Otherwise, dot notation reads a nested property ('meta.id'). For arrays of arrays, the index of the value as a string ('0'). |
| A function | A function that receives the source row and returns its id. |
true | Handsontable generates the ids: a number for each row, never reused within the instance. |
false | No row ids. This is the default behavior. |
gridSettings: GridSettings = { data: [ { sku: 'SKU-4821', product: 'Wireless Mouse', price: 25 }, { sku: 'SKU-0093', product: 'Stainless Steel Water Bottle', price: 18 }, ], rowId: 'sku', columnSorting: true, // licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/};To build an id from several values, use a function. Return null while a row lacks the values, so empty rows (for example, the rows minSpareRows adds) do not all share one id:
rowId: (row) => (row.country == null || row.code == null ? null : `${row.country}-${row.code}`),When your data has no id field, let Handsontable generate the ids:
rowId: true,Keep the ids unique. If two rows share an id, the lookups return the row with the lower physical index, and Handsontable logs a console warning.
The lookups compare ids by identity (===), so use strings or numbers. An object id matches only the same object.
Choose between generated and keyed ids
| Your case | Use |
|---|---|
| The ids only need to last while the grid is open | rowId: true |
You replace or reorder the data (loadData(), updateData()) | A row key (a property or a function) |
| You send changes to a server, or store the ids anywhere | A row key |
| You use nested rows | A row key |
Generated ids belong to the grid, not to the data:
loadData()gives every row a new id.updateData()keeps the ids by position. If the new data lists the records in another order, the ids move to other records.- A settings update keeps the ids, including one that changes
columns.
A row key reads the id from each record, so it survives any data change.
Read and look up row ids
| Method | Returns |
|---|---|
getRowId(row) | The id of the row at a visual index. |
getRowIdAtPhysicalRow(physicalRow) | The id of the row at a physical index. |
getRowIds(rows) | The ids of several visual rows, or of every row. |
getVisualRowById(id) | The visual index of the row that has the id. |
getVisualRowsByIds(ids) | The visual indexes of the rows that have the ids. |
getPhysicalRowById(id) | The physical index of the row that has the id. |
getPhysicalRowsByIds(ids) | The physical indexes of the rows that have the ids. |
const id = hot.getRowId(0); // 'SKU-4821'
hot.getPlugin('columnSorting').sort({ column: 2, sortOrder: 'asc' });
hot.getVisualRowById(id); // 1 - the Wireless Mouse row moved downhot.getRowId(1); // 'SKU-4821'The methods return null when they find nothing:
getRowId()andgetRowIdAtPhysicalRow()returnnullfor a row index out of range, for a row without an id, and when no row ids are configured.- The lookups return
nullfor an id that no row has, for example the id of a removed row. getVisualRowById()returnsnullfor a row that is trimmed or filtered out, because such a row has no visual index, and for a row pastmaxRows.getPhysicalRowById()still finds it.- A hidden row keeps its visual index, so
getVisualRowById()finds it.
Hooks such as beforeRemoveRow pass physical row indexes. Read their ids with getRowIdAtPhysicalRow(), which also works for trimmed and filtered-out rows.
Write to a row by its id
setDataAtRowIdProp() writes a value to the row that has an id, wherever the row is now. It returns false and does nothing when no row has the id.
For example, to apply the result of an asynchronous request to the record it was made for:
const id = hot.getRowId(selectedRow);const price = await fetchPrice(id);
// The user may have sorted the rows or removed the record in the meantime.hot.setDataAtRowIdProp(id, 'price', price, 'priceService');For a visible row (hidden rows included), the method works like setDataAtRowProp(). For a row that is trimmed or filtered out, it writes to the source data, so the value is not validated and afterChange does not fire for it.
Cancel pending work when a row is removed
The afterRowIdsRemoved hook passes the ids of rows that stopped existing. It fires after a row removal (an undo or a redo included), and after loadData() or updateData() replaced the data with data that no longer holds those ids.
- The hook fires in a microtask, once the call that removed the rows has finished, with every id that call removed. Rows a call takes away and puts back, such as a nested rows detach or move, are not reported.
- A trimmed or filtered-out row still exists, so the hook does not report it.
- With a data provider, loading a page, a sort, or a filter does not count as a removal, because the rows still exist on the server. A removal the server confirms is reported, with the
'dataProvider'source.
The afterRowIdsReset hook fires when a settings update changes how rows get their ids. Every id read before it may now name another row, so cancel everything.
const pendingRequests = new Map(); // row id -> AbortController
hot.addHook('afterRowIdsRemoved', (rowIds) => { rowIds.forEach((id) => { pendingRequests.get(id)?.abort(); pendingRequests.delete(id); });});
hot.addHook('afterRowIdsReset', () => { pendingRequests.forEach(controller => controller.abort()); pendingRequests.clear();});When you pass a function as rowId, pass the same function on every settings update. A new function counts as a change, and afterRowIdsReset fires each time.
Define the rowId function once, as a class field, so every settings update passes the same function.
Row ids with a data provider
When the dataProvider option sets its own rowId, Handsontable reads row ids with dataProvider.rowId, and the row id methods use it too. A rowId option with a different value is ignored, with a console warning.
Known limitations
-
A row key is read from the data every time. Change ids through the API (for example,
setDataAtRowProp()), so the lookups find a new id right away. A new id written directly into the source data may not be found until Handsontable tracks another change to the data. -
With nested rows, use a row key. Generated ids stay with row positions when a row is moved or detached between parents, so they no longer match the moved records. Handsontable logs a console warning for this combination.
-
With
dataDotNotationset tofalse, a string key with a dot still reads a nested property when the row has no property named exactly as the key. A column with the samedatapath shows nothing for that row, while the row still has an id.
Related API reference
- Configuration options:
- Core methods:
- Hooks: