stagger

function experimental

function stagger(timings: string | number, animation: AnimationMetadata | AnimationMetadata[]): AnimationStaggerMetadata;

Description

stagger is an animation-specific function that is designed to be used inside of Angular's animation DSL language. It is designed to be used inside of an animation query() and works by issuing a timing gap between after each queried item is animated.

Usage

In the example below there is a container element that wraps a list of items stamped out by an ngFor. The container element contains an animation trigger that will later be set to query for each of the inner items.

<!-- list.component.html -->
<button (click)="toggle()">Show / Hide Items</button>
<hr />
<div [@listAnimation]="items.length">
  <div *ngFor="let item of items">
    {{ item }}
  </div>
</div>

The component code for this looks as such:

import {trigger, transition, style, animate, query, stagger} from '@angular/animations';
@Component({
  templateUrl: 'list.component.html',
  animations: [
    trigger('listAnimation', [
       //...
    ])
  ]
})
class ListComponent {
  items = [];

  showItems() {
    this.items = [0,1,2,3,4];
  }

  hideItems() {
    this.items = [];
  }

  toggle() {
    this.items.length ? this.hideItems() : this.showItems();
  }
}

And now for the animation trigger code:

trigger('listAnimation', [
  transition('* => *', [ // each time the binding value changes
    query(':leave', [
      stagger(100, [
        animate('0.5s', style({ opacity: 0 }))
      ])
    ]),
    query(':enter', [
      style({ opacity: 0 }),
      stagger(100, [
        animate('0.5s', style({ opacity: 1 }))
      ])
    ])
  ])
])

Now each time the items are added/removed then either the opacity fade-in animation will run or each removed item will be faded out. When either of these animations occur then a stagger effect will be applied after each item's animation is started.