Skip to content

Tracking in @for (and the trackBy legacy)

When a collection changes, Angular has to work out which DOM nodes correspond to which items. The track expression is how you tell it.

Get it right and Angular performs the minimum DOM operations — moving nodes, updating bindings on the ones that stayed. Get it wrong and it destroys and recreates every row.

That is not just a performance difference. Destroying a row destroys its component instance, so:

  • Focus is lost. The user is typing in a cell and the input disappears.
  • Scroll position resets.
  • Component state is lost — an expanded panel collapses, an in-progress edit vanishes.
  • Animations restart.
  • Every child component is constructed again, re-running its subscriptions and effects.

The bug is almost always reported as “the list flickers” or “my input loses focus while I type”, and it is almost always the tracking expression.

@for makes track required, which is the single best thing about the new syntax: the framework’s most common performance mistake is now a compile error.

@for (order of orders(); track order.id) {
<order-row [order]="order" />
}

Track a property that uniquely identifies the item. id, uuid, a natural key. If your data has no such field, Angular’s guidance is to strongly consider adding one — and that guidance is right, because without an identity there is no correct answer to “is this the same item?”.

@for (label of STATIC_LABELS; track $index) {
<li>{{ label }}</li>
}

$index is correct for static collections that never change. Items never move, never get inserted in the middle, never get removed — so position is identity.

It is wrong for anything sortable, filterable, or where items can be inserted or removed anywhere but the end. Consider a list tracked by $index where the user deletes the first item: index 0 now holds what was item 1, index 1 holds what was item 2, and so on. Angular sees every position’s content change and updates every row’s bindings, keeping the DOM node that had item 0’s focus and scroll but now shows item 1’s data. It “works” and behaves wrongly.

@for (item of items; track item) {
{{ item.name }}
}

This uses reference identity (===). Angular’s documentation is direct: avoid this whenever possible, as it can lead to significantly slower rendering updates, because Angular has no way to map which data item corresponds to which DOM nodes.

It is specifically bad when the data comes from an API, because every fetch produces new object references for logically identical items — so every refresh destroys and rebuilds the entire list.

When no single field is unique, build one — but keep it cheap and stable:

@for (cell of cells(); track cell.row + ':' + cell.column) {
<grid-cell [cell]="cell" />
}

The expression is evaluated for every item on every update, so avoid JSON.stringify or anything allocating.

The tracking value must be unique. Duplicates cause an Angular runtime error, and it is a genuinely useful one — it usually means the field you assumed was a key is not.

@for behaves better than *ngFor here, and it is worth knowing exactly how:

If a tracked property changes while the object reference stays the same, Angular updates the view’s bindings — including component inputs — rather than destroying and recreating the element.

@for prioritises view reuse. Where *ngFor would tear down and rebuild, @for re-binds. In practice that means fewer situations where a “wrong” track choice is catastrophic — but it does not make a wrong choice right, because identity confusion still puts the wrong data in the DOM node holding a user’s focus.

Symptom Likely cause
Input loses focus while typing in a list Tracking causes recreation on each update
List visibly flickers on refresh Tracking by reference; new objects from the API
Expanded rows collapse after an update Row components destroyed and recreated
Wrong row highlighted after a delete $index on a mutable list
Animations restart on unrelated changes Views recreated
“Duplicate keys” runtime error The track expression is not unique
Scrolling a large list is slow No tracking problem — you need virtual scrolling

A quick way to confirm: open DevTools’ Elements panel and watch the list while the data updates. If rows flash as removed-and-added rather than updating in place, tracking is the problem.

That last row deserves emphasis: track is not a fix for rendering too many rows. With 10,000 rows, correct tracking makes updates efficient, but you still have 10,000 component instances with their subscriptions and DOM. That needs virtual scrolling (cdk-virtual-scroll-viewport) or server-side pagination. Tracking and windowing solve different problems, and people frequently reach for the first when they need the second.

<!-- Before -->
<li *ngFor="let order of orders; trackBy: trackByOrderId">{{ order.name }}</li>
<!-- After -->
@for (order of orders; track order.id) {
<li>{{ order.name }}</li>
}
// The component method is no longer needed.
trackByOrderId(index: number, order: Order): string {
return order.id;
}

The expression replaces the method entirely — no (index, item) signature, no boilerplate function per list.

The control-flow migration schematic converts *ngFor without trackBy to track $index. That preserves the old behaviour exactly, and for a mutable list the old behaviour was the bug. Grep for track $index after migrating and fix every list that is not genuinely static — this is the highest-value review step in that migration.

Terminal window
ng generate @angular/core:control-flow