From 48262bcb70dc4d754cf51679a8a063d94846ee38 Mon Sep 17 00:00:00 2001 From: Dario Piotrowicz Date: Mon, 27 Dec 2021 12:30:08 +0100 Subject: [PATCH] docs(animations): add section about animating reordering list items (#44567) add a section regarding reordering list items in the complex animation sequences guide to help developers rememeber to use a `TrackByFunction` whenever they are animating `*ngFor` list items which change their ordering as suggested here: https://github.com/angular/angular/issues/42750#issuecomment-979127165 relates to issue #28040 and #42750 PR Close #44567 --- aio/content/guide/complex-animation-sequences.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/aio/content/guide/complex-animation-sequences.md b/aio/content/guide/complex-animation-sequences.md index da443d7822b..485c6ee6ca1 100644 --- a/aio/content/guide/complex-animation-sequences.md +++ b/aio/content/guide/complex-animation-sequences.md @@ -88,6 +88,16 @@ For each change: * If there are multiple elements entering or leaving the DOM, staggers each animation starting at the top of the page, with a 50-millisecond delay between each element. +## Animating the items of a reordering list + +Although Angular animates correctly `*ngFor` list items out of the box, it will not be able to do so if their ordering changes. This is because it will lose track of which element is which, resulting in broken animations. The only way to help Angular keep track of such elements is by assigning a `TrackByFunction` to the `NgForOf` directive. This makes sure that Angular always knows which element is which, thus allowing it to apply the correct animations to the correct elements all the time. + +
+ +**Rule of Thumb:** If you need to animate the items of an `*ngFor` list and there is a possibility that the order of such items will change during runtime, always use a `TrackByFunction`. + +
+ ## Animation sequence summary Angular functions for animating multiple elements start with `query()` to find inner elements, for example gathering all images within a `
`. The remaining functions, `stagger()`, [group](api/animations/group)(), and `sequence()`, apply cascades or lets you control how multiple animation steps are applied.