# `ngAnimate` (directive in module `ng` )

Improve this doc

## Description

The `ngAnimate` directive works as an attribute that is attached alongside pre-existing directives. It effects how the directive will perform DOM manipulation. This allows for complex animations to take place while without burduning the directive which uses the animation with animation details. The built dn directives `ngRepeat`, `ngInclude`, `ngSwitch`, `ngShow`, `ngHide` and `ngView` already accept `ngAnimate` directive. Custom directives can take advantage of animation through `$animator service`.

Below is a more detailed breakdown of the supported callback events provided by pre-exisitng ng directives:

- `ngRepeat` — enter, leave and move
- `ngView` — enter and leave
- `ngInclude` — enter and leave
- `ngSwitch` — enter and leave
- `ngShow & ngHide` - show and hide respectively

You can find out more information about animations upon visiting each directive page.

Below is an example of a directive that makes use of the ngAnimate attribute:

    <!-- you can also use data-ng-animate, ng:animate or x-ng-animate as well -->
    <ANY ng-directive ng-animate="{event1: 'animation-name', event2: 'animation-name-2'}"></ANY>

    <!-- you can also use a short hand -->
    <ANY ng-directive ng-animate=" 'animation' "></ANY>
    <!-- which expands to -->
    <ANY ng-directive ng-animate="{ enter: 'animation-enter', leave: 'animation-leave', ...}"></ANY>

    <!-- keep in mind that ng-animate can take expressions -->
    <ANY ng-directive ng-animate=" computeCurrentAnimation() "></ANY>

The `event1` and `event2` attributes refer to the animation events specific to the directive that has been assigned.

#### CSS-defined Animations

By default, ngAnimate attaches two CSS3 classes per animation event to the DOM element to achieve the animation. This is up to you, the developer, to ensure that the animations take place using cross-browser CSS3 transitions. All that is required is the following CSS code:

    <style type="text/css">
    /*
     The animate-enter prefix is the event name that you
     have provided within the ngAnimate attribute.
    */
    .animate-enter-setup {
     -webkit-transition: 1s linear all; /* Safari/Chrome */
     -moz-transition: 1s linear all; /* Firefox */
     -ms-transition: 1s linear all; /* IE10 */
     -o-transition: 1s linear all; /* Opera */
     transition: 1s linear all; /* Future Browsers */

     /* The animation preparation code */
     opacity: 0;
    }

    /*
     Keep in mind that you want to combine both CSS
     classes together to avoid any CSS-specificity
     conflicts
    */
    .animate-enter-setup.animate-enter-start {
     /* The animation code itself */
     opacity: 1;
    }
    </style>

    <div ng-directive ng-animate="{enter: 'animate-enter'}"></div>

Upon DOM mutation, the setup class is added first, then the browser is allowed to reflow the content and then, the start class is added to trigger the animation. The ngAnimate directive will automatically extract the duration of the animation to determine when the animation ends. Once the animation is over then both CSS classes will be removed from the DOM. If a browser does not support CSS transitions then the animation will start and end immediately resulting in a DOM element that is at it's final state. This final state is when the DOM element has no CSS animation classes surrounding it.

#### JavaScript-defined Animations

In the event that you do not want to use CSS3 animations or if you wish to offer animations to browsers that do not yet support them, then you can make use of JavaScript animations defined inside ngModule.

    var ngModule = angular.module('YourApp', []);
    ngModule.animation('animate-enter', function() {
      return {
        setup : function(element) {
          //prepare the element for animation
          element.css({ 'opacity': 0 });
          var memo = "..."; //this value is passed to the start function
          return memo;
        },
        start : function(element, done, memo) {
          //start the animation
          element.animate({
            'opacity' : 1
          }, function() {
            //call when the animation is complete
            done()
          });
        }
      }
    });

As you can see, the JavaScript code follows a similar template to the CSS3 animations. Once defined, the animation can be used in the same way with the ngAnimate attribute. Keep in mind that, when using JavaScript-enabled animations, ngAnimate will also add in the same CSS classes that CSS-enabled animations do (even if you're using JavaScript animations) to animated the element, but it will not attempt to find any CSS3 transition duration value. It will instead close off the animation once the provided done function is executed. So it's important that you make sure your animations remember to fire off the done function once the animations are complete.

## Usage

as attribute

    <ANY ng-animate="{expression}">
       ...
    </ANY>

as class

    <ANY class="ng-animate: {expression};">
       ...
    </ANY>

### Parameters

- `ngAnimate – {expression} –`

  Used to configure the DOM manipulation animations.