Row Identity

trackBy: 'id'      // left
trackBy: undefined // right

trackBy: (_index, row) => `${row.region}:${row.code}`

The problem it solves

The grid regularly holds row objects that are not the ones your code is holding. Anything that came over HTTP was parsed into fresh objects; anything you edit produces a new object rather than mutating the old one. Comparing by reference then says "I have never seen this row" about a row the reader is looking at.

trackBy is how you tell the grid what makes a row that row. Give it the field that identifies one, and it can match your object to the one on screen. Without it, the identity falls back to the row object itself — correct, but true of almost nothing.

What stops working without it

• Targeted updates match nothing. applyTransaction() finds rows to update or remove by id. With no trackBy, an update applies to zero rows and a removal removes none — which is exactly what the demo above shows, along with the count the call hands back. The grid also logs one console warning rather than failing silently.
• Measured row heights are re-measured. With content-driven heights the cache is keyed by row id, so without one every reload starts from scratch. See Auto Row Height.
• Anything you build on row identity. Your own code usually needs the same answer — which row was clicked, which rows are pending, which row a websocket message is about. Deriving it once in trackBy keeps your answer and the grid's the same one.

None of these throw. That is what makes the option worth a page: the failure mode is a feature quietly doing nothing, which is the hardest kind to notice and the cheapest kind to prevent.

Two forms

// A property name — the common case, and enough whenever your rows carry a unique field.
trackBy: 'id'

// A function — for a composite key, a nested id, or an id you have to derive.
trackBy: (index, row) => row.tenantId + ':' + row.id

The function form receives the row index as well, but do not use it: an index is a position, not an identity, and it changes the moment anything is sorted, filtered or paged — which reintroduces the exact problem the option exists to solve.

What makes a good id

• Unique across every row the grid can hold, not just the current page. Two rows sharing an id are treated as one.
• Stable — the same row keeps the same id across reloads and edits. An id derived from a value the reader can edit is not stable.
• Primitive — a number or a string. Ids are compared by value, so an object works only if it is literally the same object, which puts you back where you started.

Replacing your data, or changing it in place

There are two ways to get new values into a grid, and they are not the same thing. Replacing means handing the grid a fresh array — a new fetch, a reload, an immutable state update. Changing in place means pushing individual rows through applyTransaction() and leaving the rest of the data alone.

Both are supported, and trackBy is what makes either survive. When you replace the data, every row object is new; without an id the grid has no way to recognise them as the rows it was already showing, so selection, expansion, focus and measured heights are discarded along with the objects. With an id, the same rows carry all of it across the swap and only what actually changed re-renders.

When you change rows in place, trackBy is not a nicety at all — it is the lookup. applyTransaction({ update }) and { remove } find their target by row id, so without one they match nothing and return an empty updated array. The call itself succeeds — nothing throws, nothing changes on screen, and the only sign is a development-mode console warning and a count of zero in the result you were probably not reading.

Which to reach for is a question about your application, not about the grid. Replacing is simpler and fits an immutable store; changing in place is what you want when updates arrive one at a time and re-rendering the whole set would be wasteful. Give rows a stable id and you are free to do either — or both, on the same grid.

Setting it once

If your rows all carry the same id field, set it for the whole app rather than per grid:

// app.config.ts
providers: [
  provideGridDefaults({ trackBy: 'id' }),
]

A grid whose rows use a different field still overrides it locally. See Global Configuration.