@mgechev there is my first iteration on trackBy topic.
I also would like to add persistence advantage of using tracking function. The idea is simple: given that rendered collection of video players, each one has the "like" button. User starts to play one video and in the middle of the process clicks "like". If an immutable collection is used (which is true in most cases, as it's suggested practice) then without trackBy DOM tree re-renders again to alter collection state. Which causes that player is stopped because it is totally new player has been rendered on its place.

But i am afraid describing this in good words and complete example will dramatically increase paragraph length which makes it less chance to be finished by the reader.

Do you think it worth adding it?

Draft

trackBy option for *ngFor directive

The *ngFor directive is used for rendering a collection.
By default *ngFor doesn't know how to identify each item of the given collection.

When the collection is changed in some way then the whole DOM tree is destroyed and recreated again. This is acceptable if the collection is totally different. But most times we have just a slightly modified collection (e.g. collection is sorted or one item is added/removed/changed). Anyway DOM tree is destroyed and recreated from the scratch again. This is unnecessary and, what even more important, may lead to poor performance of the whole app, particularly on a big collection of data.

To modify this behavior it is up to developer to provide custom tracking function as trackBy option for the *ngFor directive. Tracking function takes two arguments: index and item. Angular uses the value returned from tracking function to track items identity.

Example

@Component({
  selector: 'yt-feed',
  template: `
  <h1>Your video feed</h1>
  <yt-player *ngFor="let video of feed; trackBy: trackById" [video]="video"></yt-player>
`
})
export class YtFeedComponent {
  feed = [
    {
      id: 3849, // note "id" field, we refer to it in "trackById" function
      title: "Angular in 60 minutes",
      url: "http://youtube.com/ng2-in-60-min",
      likes: "29345"    
    },
    // ...
  ];

  trackById(index, item) {
    return item.id;
  }
}

from angular-performance-checklist.

Sure, if you want you can draft the suggestions here and later move them to the list?

Thanks for the suggesting the improvements!

from angular-performance-checklist.

Sorry for the delay.

Yes, I agree that this example may get a bit too long. The draft of trackBy sounds good to me! Maybe you can provide an external reference of the advantages of trackBy in case of immutable data?

Do you want to open a PR with the suggestion?

from angular-performance-checklist.

Yes i will open PR in the middle of the week (i did not get much free time these weekends).

Could you please clarify what do you mean under

an external reference of the advantages of trackBy in case of immutable data

?

from angular-performance-checklist.

I also would like to add persistence advantage of using tracking function. The idea is simple: given that rendered collection of video players, each one has the "like" button. User starts to play one video and in the middle of the process clicks "like". If an immutable collection is used (which is true in most cases, as it's suggested practice) then without trackBy DOM tree re-renders again to alter collection state. Which causes that player is stopped because it is totally new player has been rendered on its place.

I think by itself, this deserves a short blog post. I think it's worth mentioning something like:

Introducing a trackBy function will not only improve performance but also help us determine the unchanged entries in immutable data structures. For further reference take a look here.

from angular-performance-checklist.