/ng-Fx

Simple, Beautiful animation library for Angular

Primary LanguageJavaScriptMIT LicenseMIT

ng-Fx Build Status

A simple way to add beautiful animations to your angular apps. Animations based off animate.css. All animations are built in JavaScript.

ng-Fx does not rely on CSS for animations. This allows it to be dynamic and able to adjust on the fly. The only predefined CSS classes are the animations and the easings. ng-Animate allows ng-Fx to create JavaScript based animations, so the classes do not correspond to a style in a CSS file.

Interactive Demo

Preview the goodness at hendrixer.github.io.

Dependencies

  • Angular.js (1.2+)
  • ng-Animate
  • GSAP.js

Downloading

  1. The best way to install ng-Fx is to use bower
    • bower install ng-Fx --save
  2. Or, from this repo

Installing

  1. Include angular-animate.js and ng-fx.js and TweenMax.js into your html with script tags.
  • Note: TweenMax.js must come before ng-fx.js in your HTML script tags.
  1. Include the dependencies into your angular app, fx.animations
angular.module('myApp', ['ngAnimate', 'fx.animations'])

##Using ###Animations

  • All animations are used with ng-animate. So you can apply them to...
    • ng-hide / ng-show
    • ng-include
    • ng-if
    • ng-view
    • ui-view (if you're using ui.router)
    • ng-switch
    • ng-class
    • ng-repeat
  • Adding the animations are as simple as adding a css class. ng-Fx uses the 'fx' name space. Here's an example using a fade animation. The list items will enter / leave / and move with the 'fade-down' animation. Note that ng-repeat will not trigger animations upon page load, the collection you are iterating over must be empty at first then populated, you can achieve this with a simple timeout or some other async operation.
angular.module('foodApp', ['ngAnimate', 'fx.animations'])
.controller('FoodController', function($scope, $timeout){
  $timeout(function(){
    $scope.foods = ['apple', 'muffin', 'chips'];
  }, 100);
});
<ul ng-controller="FoodController">
  <li class='fx-fade-down' ng-repeat="food in foods">
    {{ food }}
  </li>
</ul>

###Easings

  • You can also add a different easing to any animation you want. It is as easy as adding an animation, just use a CSS class. Building on the previous example, you can just add fx-easing-your easing here
<ul ng-controller="FoodController">
  <li class='fx-fade-down fx-easing-bounce' ng-repeat="food in foods">
    {{ food }}
  </li>
</ul>

###Speed

  • Adjusting the speed in the ng-fx is a snap too! Your animations speeds on which they enter and leave your app are totally up to you. You just have to add a CSS class. fx-speed-your speed in milliseconds. All animations have their own default speed if not provided by you. There are no predefined classes for speeds. Any speed (in ms) can be accepted.
<ul ng-controller="FoodController">
  <li class='fx-fade-down fx-easing-bounce fx-speed-800' ng-repeat="food in foods">
    {{ food }}
  </li>
</ul>

###Events

  • Animations will emit events to your app when they have finished. You can listen to these events in your controllers and directives to perform other things. When an animation is complete the event will look like so ' [animation name] + [enter or leave]', for example 'fade-down enter'. You just have to add the CSS class fx-trigger to an animated element.
angular.module('myApp', ['ngAnimate', 'fx.animations'])
.controller('FoodController', function($scope, $timeout){
  $timeout(function(){
    $scope.foods = ['apple', 'muffin', 'chips'];
  }, 100);
})
.directive('goAway', function($animate){
  function link(scope, element){
    scope.$on('fade-down enter', function(){
      $animate.leave(element);
    });
  }
  return {
    restrict: 'A',
    link: link
  };
});
<div ng-controller="FoodController">
  <h1 go-away class='fx-zoom-up'> This will zoom out when the fade animation is done</h1>
  <ul>
    <li class='fx-fade-down fx-easing-bounce fx-speed-800 fx-trigger' ng-repeat="food in foods">
      {{ food }}
    </li>
  </ul>
</div>

###List of animations and ease types

##What's next

  • More animations
  • More flexibility
  • Easy api to create your own animations
  • Events triggered are unique to element and not just animation type

##Contributing

  1. Fork it
  2. Clone your fork
  3. Create new branch
  4. Make changes
  5. Make test and check test
  6. Build it, run gulp and the files will be linted, concatenated, and minified
  7. Push to new branch on your forked repo
  8. Pull request from your branch to ng-Fx master

###Format for pull request

  • Pretty standard
    • in your commit message; (type) message [issue # closed]
      • (bug) killed that bug, closes #45
    • if you're submitting new animations:
      • (new fx) added 3d rotation animation
  • Submit issues as you see them. There are probably better, faster, easier ways to achieve what ng-Fx is designed to do so.

###Testing

  • ng-Fx uses Karma + Jasmine + Travis for unit and ci
  • Make sure you didn't break anything
    • run karma start or npm test
  • Features will not be accepted without specs created for them.