Improve this DocAnimations

AngularJS 1.3 provides animation hooks for common directives such as ngRepeat, ngSwitch, and ngView, as well as custom directives via the $animate service. These animation hooks are set in place to trigger animations during the life cycle of various directives and when triggered, will attempt to perform a CSS Transition, CSS Keyframe Animation or a JavaScript callback Animation (depending on if an animation is placed on the given directive). Animations can be placed using vanilla CSS by following the naming conventions set in place by AngularJS or with JavaScript code when it's defined as a factory.

Animations are not available unless you include the ngAnimate module as a dependency within your application.

Below is a quick example of animations being enabled for ngShow and ngHide:

Installation

See the API docs for ngAnimate for instructions on installing the module.

You may also want to setup a separate CSS file for defining CSS-based animations.

How they work

Animations in AngularJS are completely based on CSS classes. As long as you have a CSS class attached to a HTML element within your website, you can apply animations to it. Lets say for example that we have an HTML template with a repeater in it like so:

<div ng-repeat="item in items" class="repeated-item">
  {{ item.id }}
</div>

As you can see, the .repeated-item class is present on the element that will be repeated and this class will be used as a reference within our application's CSS and/or JavaScript animation code to tell AngularJS to perform an animation.

As ngRepeat does its thing, each time a new item is added into the list, ngRepeat will add a ng-enter class name to the element that is being added. When removed it will apply a ng-leave class name and when moved around it will apply a ng-move class name.

Taking a look at the following CSS code, we can see some transition and keyframe animation code set for each of those events that occur when ngRepeat triggers them:

/*
  We're using CSS transitions for when
  the enter and move events are triggered
  for the element that has the .repeated-item
  class
*/
.repeated-item.ng-enter, .repeated-item.ng-move {
  -webkit-transition:0.5s linear all;
  -moz-transition:0.5s linear all;
  -o-transition:0.5s linear all;
  transition:0.5s linear all;
  opacity:0;
}

/*
 The ng-enter-active and ng-move-active
 are where the transition destination properties
 are set so that the animation knows what to
 animate.
*/
.repeated-item.ng-enter.ng-enter-active,
.repeated-item.ng-move.ng-move-active {
  opacity:1;
}

/*
  We're using CSS keyframe animations for when
  the leave event is triggered for the element
  that has the .repeated-item class
*/
.repeated-item.ng-leave {
  -webkit-animation:0.5s my_animation;
  -moz-animation:0.5s my_animation;
  -o-animation:0.5s my_animation;
  animation:0.5s my_animation;
}

@keyframes my_animation {
  from { opacity:1; }
  to { opacity:0; }
}

/*
  Unfortunately each browser vendor requires
  its own definition of keyframe animation code...
*/
@-webkit-keyframes my_animation {
  from { opacity:1; }
  to { opacity:0; }
}

@-moz-keyframes my_animation {
  from { opacity:1; }
  to { opacity:0; }
}

@-o-keyframes my_animation {
  from { opacity:1; }
  to { opacity:0; }
}

The same approach to animation can be used using JavaScript code (jQuery is used within to perform animations):

myModule.animation('.repeated-item', function() {
  return {
    enter : function(element, done) {
      element.css('opacity',0);
      jQuery(element).animate({
        opacity: 1
      }, done);

      // optional onDone or onCancel callback
      // function to handle any post-animation
      // cleanup operations
      return function(isCancelled) {
        if(isCancelled) {
          jQuery(element).stop();
        }
      }
    },
    leave : function(element, done) {
      element.css('opacity', 1);
      jQuery(element).animate({
        opacity: 0
      }, done);

      // optional onDone or onCancel callback
      // function to handle any post-animation
      // cleanup operations
      return function(isCancelled) {
        if(isCancelled) {
          jQuery(element).stop();
        }
      }
    },
    move : function(element, done) {
      element.css('opacity', 0);
      jQuery(element).animate({
        opacity: 1
      }, done);

      // optional onDone or onCancel callback
      // function to handle any post-animation
      // cleanup operations
      return function(isCancelled) {
        if(isCancelled) {
          jQuery(element).stop();
        }
      }
    },

    // you can also capture these animation events
    addClass : function(element, className, done) {},
    removeClass : function(element, className, done) {}
  }
});

With these generated CSS class names present on the element at the time, AngularJS automatically figures out whether to perform a CSS and/or JavaScript animation. If both CSS and JavaScript animation code is present, and match the CSS class name on the element, then AngularJS will run both animations at the same time.

Class and ngClass animation hooks

AngularJS also pays attention to CSS class changes on elements by triggering the add and remove hooks. This means that if a CSS class is added to or removed from an element then an animation can be executed in between, before the CSS class addition or removal is finalized. (Keep in mind that AngularJS will only be able to capture class changes if an expression or the ng-class directive is used on the element.)

The example below shows how to perform animations during class changes:

Although the CSS is a little different than what we saw before, the idea is the same.

Which directives support animations?

A handful of common AngularJS directives support and trigger animation hooks whenever any major event occurs during its life cycle. The table below explains in detail which animation events are triggered

Directive	Supported Animations
ngRepeat	enter, leave, and move
ngView	enter and leave
ngInclude	enter and leave
ngSwitch	enter and leave
ngIf	enter and leave
ngClass or {{class}}	add and remove
ngShow & ngHide	add and remove (the ng-hide class value)

For a full breakdown of the steps involved during each animation event, refer to the API docs.

How do I use animations in my own directives?

Animations within custom directives can also be established by injecting $animate directly into your directive and making calls to it when needed.

myModule.directive('my-directive', ['$animate', function($animate) {
  return function(scope, element, attrs) {
    element.on('click', function() {
      if(element.hasClass('clicked')) {
        $animate.removeClass(element, 'clicked');
      } else {
        $animate.addClass(element, 'clicked');
      }
    });
  };
}]);

Preventing flicker before an animation starts

When nesting elements with structural animations such as ngIf into elements that have class-based animations such as ngClass, it sometimes happens that before the actual animation starts, there is a brief flicker or flash of content where the animated element is briefly visible.

To prevent this, you can apply styles to the ng-[event]-prepare class, which is added as soon as an animation is initialized, but removed before the actual animation starts (after waiting for a $digest). This class is only added for structural animations (enter, move, and leave).

Here's an example where you might see flickering:

<div ng-class="{red: myProp}">
  <div ng-class="{blue: myProp}">
    <div class="message" ng-if="myProp"></div>
  </div>
</div>

It is possible that during the enter event, the .message div will be briefly visible before it starts animating. In that case, you can add styles to the CSS that make sure the element stays hidden before the animation starts:

.message.ng-enter-prepare {
  opacity: 0;
}

/* Other animation styles ... */

More about animations

For a full breakdown of each method available on $animate, see the API documentation.

To see a complete demo, see the animation step within the AngularJS phonecat tutorial.