animateChild

function experimental

npm Package	@angular/animations
Module	import { animateChild } from '@angular/animations';
Source	animations/src/animation_metadata.ts

function animateChild(options: AnimateChildOptions | null = null): AnimationAnimateChildMetadata;

Description

animateChild is an animation-specific function that is designed to be used inside of Angular's animation DSL language. It works by allowing a queried element to execute its own animation within the animation sequence.

Each time an animation is triggered in angular, the parent animation will always get priority and any child animations will be blocked. In order for a child animation to run, the parent animation must query each of the elements containing child animations and then allow the animations to run using animateChild.

The example HTML code below shows both parent and child elements that have animation triggers that will execute at the same time.

<!-- parent-child.component.html -->
<button (click)="exp =! exp">Toggle</button>
<hr>

<div [@parentAnimation]="exp">
  <header>Hello</header>
  <div [@childAnimation]="exp">
      one
  </div>
  <div [@childAnimation]="exp">
      two
  </div>
  <div [@childAnimation]="exp">
      three
  </div>
</div>

Now when the exp value changes to true, only the parentAnimation animation will animate because it has priority. However, using query and animateChild each of the inner animations can also fire:

// parent-child.component.ts
import {trigger, transition, animate, style, query, animateChild} from '@angular/animations';
@Component({
  selector: 'parent-child-component',
  animations: [
    trigger('parentAnimation', [
      transition('false => true', [
        query('header', [
          style({ opacity: 0 }),
          animate(500, style({ opacity: 1 }))
        ]),
        query('@childAnimation', [
          animateChild()
        ])
      ])
    ]),
    trigger('childAnimation', [
      transition('false => true', [
        style({ opacity: 0 }),
        animate(500, style({ opacity: 1 }))
      ])
    ])
  ]
})
class ParentChildCmp {
  exp: boolean = false;
}

In the animation code above, when the parentAnimation transition kicks off it first queries to find the header element and fades it in. It then finds each of the sub elements that contain the @childAnimation trigger and then allows for their animations to fire.

This example can be further extended by using stagger:

query('@childAnimation', stagger(100, [
  animateChild()
]))

Now each of the sub animations start off with respect to the 100ms staggering step.

The first frame of child animations

When sub animations are executed using animateChild the animation engine will always apply the first frame of every sub animation immediately at the start of the animation sequence. This way the parent animation does not need to set any initial styling data on the sub elements before the sub animations kick off.

In the example above the first frame of the childAnimation's false => true transition consists of a style of opacity: 0. This is applied immediately when the parentAnimation animation transition sequence starts. Only then when the @childAnimation is queried and called with animateChild will it then animate to its destination of opacity: 1.

Note that this feature designed to be used alongside query() and it will only work with animations that are assigned using the Angular animation DSL (this means that CSS keyframes and transitions are not handled by this API).