transition

Experimental Function

Class Export

export transition(stateChangeExpr: string, steps: AnimationMetadata | AnimationMetadata[]) : AnimationStateTransitionMetadata

transition is an animation-specific function that is designed to be used inside of Angular2's animation DSL language. If this information is new, please navigate to the component animations metadata page to gain a better understanding of how animations in Angular2 are used.

transition declares the sequence of animation steps that will be run when the provided stateChangeExpr value is satisfied. The stateChangeExpr consists of a state1 => state2 which consists of two known states (use an asterix (*) to refer to a dynamic starting and/or ending state).

Animation transitions are placed within an animation trigger. For an transition to animate to a state value and persist its styles then one or more animation states is expected to be defined.

Usage

An animation transition is kicked off the stateChangeExpr predicate evaluates to true based on what the previous state is and what the current state has become. In other words, if a transition is defined that matches the old/current state criteria then the associated animation will be triggered.

// all transition/state changes are defined within an animation trigger
trigger("myAnimationTrigger", [
  // if a state is defined then its styles will be persisted when the
  // animation has fully completed itself
  state("on", style({ background: "green" })),
  state("off", style({ background: "grey" })),

  // a transition animation that will be kicked off when the state value
  // bound to "myAnimationTrigger" changes from "on" to "off"
  transition("on => off", animate(500)),

  // it is also possible to do run the same animation for both directions
  transition("on <=> off", animate(500)),

  // or to define multiple states pairs separated by commas
  transition("on => off, off => void", animate(500)),

  // this is a catch-all state change for when an element is inserted into
  // the page and the destination state is unknown
  transition("void => *", [
    style({ opacity: 0 }),
    animate(500)
  ]),

  // this will capture a state change between any states
  transition("* => *", animate("1s 0s")),
])

The template associated with this component will make use of the myAnimationTrigger animation trigger by binding to an element within its template code.

<!-- somewhere inside of my-component-tpl.html -->
<div [@myAnimationTrigger]="myStatusExp">...</div>

The final animate call

If the final step within the transition steps is a call to animate() that only uses a timing value with no style data then it will be automatically used as the final animation arc for the element to animate itself to the final state. This involves an automatic mix of adding/removing CSS styles so that the element will be in the exact state it should be for the applied state to be presented correctly.

// start off by hiding the element, but make sure that it animates properly to whatever state
// is currently active for "myAnimationTrigger"
transition("void => *", [
  style({ opacity: 0 }),
  animate(500)
])

Transition Aliases (:enter and :leave)

Given that enter (insertion) and leave (removal) animations are so common, the transition function accepts both :enter and :leave values which are aliases for the void => * and * => void state changes.

transition(":enter", [
  style({ opacity: 0 }),
  animate(500, style({ opacity: 1 }))
])
transition(":leave", [
  animate(500, style({ opacity: 0 }))
])

Example (live demo)

import {Component, NgModule, animate, state, style, transition, trigger} from '@angular/core';
import {BrowserModule} from '@angular/platform-browser';

@Component({
  selector: 'example-app',
  styles: [`
    .toggle-container {
      background-color:white;
      border:10px solid black;
      width:200px;
      text-align:center;
      line-height:100px;
      font-size:50px;
      box-sizing:border-box;
      overflow:hidden;
    }
  `],
  animations: [trigger(
      'openClose',
      [
        state('collapsed, void', style({height: '0px', color: 'maroon', borderColor: 'maroon'})),
        state('expanded', style({height: '*', borderColor: 'green', color: 'green'})),
        transition(
            'collapsed <=> expanded', [animate(500, style({height: '250px'})), animate(500)])
      ])],
  template: `
    <button (click)="expand()">Open</button>
    <button (click)="collapse()">Closed</button>
    <hr />
    <div class="toggle-container" [@openClose]="stateExpression">
      Look at this box
    </div>
  `
})
export class MyExpandoCmp {
  stateExpression: string;
  constructor() { this.collapse(); }
  expand() { this.stateExpression = 'expanded'; }
  collapse() { this.stateExpression = 'collapsed'; }
}

@NgModule({imports: [BrowserModule], declarations: [MyExpandoCmp], bootstrap: [MyExpandoCmp]})
export class AppModule {
}

exported from @angular/core/index defined in @angular/core/src/animation/metadata.ts