jquery.gsap.js

Good news for anyone using jQuery.animate() - the new jquery.gsap.js plugin allows you to have GSAP take control under the hood so that your animations perform better; no need to change any of your code. Plus GSAP adds numerous capabilities, allowing you to tween colors, 2D transforms (rotation, scaleX, scaleY, skewX, skewY, x, y), 3D transforms (rotationX, rotationY, z, perspective), backgroundPosition, boxShadow, and lots more. You can even animate to a different className! This plugin makes it very easy to audition GSAP in your project without needing to learn a new API. We still highly recommend learning the regular GSAP API because it's much more flexible, robust, and object-oriented than jQuery.animate(), but for practical purposes this plugin delivers a bunch of power with almost zero effort.

Benefits

• Up to 20x faster than jQuery's native animate() method. See the interactive speed comparison for yourself.
• Works exactly the same as the regular jQuery.animate() method. Same syntax. No need to change your code. Just load the plugin (and TweenMax or TweenLite & CSSPlugin) and you're done.
• Adds the ability to animate additional properties (without vendor prefixes):
  • colors (backgroundColor, borderColor, color, etc.)
  • boxShadow
  • textShadow
  • 2D transforms like rotation, scaleX, scaleY, x, y, skewX, and skewY, including 2D transformOrigin functionality
  • 3D transforms like rotationY rotationX, z, and perspective, including 3D transformOrigin functionality
  • borderRadius (without the need to define each corner and use browser prefixes)
  • className which allows you to define a className (or use “+=” or “-=” to add/remove a class) and have the engine figure out which properties are different and animate the differences using whatever ease and duration you want.
  • backgroundPosition
  • clip
• Animate along Bezier curves, even rotating along with the path or plotting a smoothly curved Bezier through a set of points you provide (including 3D!). GSAP’s Bezier system is super flexible in that it’s not just for x/y/z coordinates – it can handle ANY set of properties. Plus it will automatically adjust the movement so that it’s correctly proportioned the entire way, avoiding a common problem that plagues Bezier animation systems. You can define Bezier data as Cubic or Quadratic or raw anchor points.
• Add tons of easing options including proprietary SlowMo and SteppedEase along with all the industry standards
• When animating the rotation of an object, automatically go in the shortest direction (clockwise or counter-clockwise) using shortRotation, shortRotationX, or shortRotationY

For a detailed comparison between jQuery and GSAP, check out the cage match.

Usage

Download the files (requires version 1.8.0 (or later) of TweenMax or TweenLite!) and then add the appropriate script tags to your page. The plugin file (jquery.gsap.min.js) itself does NOT include GSAP because you get to choose which files you want to load depending on the features you want. The simplest way to get all the goodies is by loading TweenMax (which includes TweenLite, CSSPlugin, TimelineLite, TimelineMax, EasePack, BezierPlugin, and RoundPropsPlugin too). For example, assuming you put the TweenMax.min.js file into a folder named "js" which is in the same directory as your HTML file, you'd simply place the following code into your HTML file: All the goodies:

<script src="js/TweenMax.min.js"></script>
<script src="js/jquery.gsap.min.js"></script>

If, however, you're more concerned about file size and only want to use TweenLite, CSSPlugin (for animating DOM elements), and some extra eases, here is a common set of script tags: Lightweight:

<script src="js/plugins/CSSPlugin.min.js"></script>
<script src="js/easing/EasePack.min.js"></script>
<script src="js/TweenLite.min.js"></script> 
<script src="js/jquery.gsap.min.js"></script>

Then, to animate things, you can use the regular jQuery.animate() method like this:

//tween all elements with class "myClass" to top:100px and left:200px over the course of 3 seconds
$(".myClass").animate({top:100, left:200}, 3000);

//do the same thing, but with a Strong.easeOut ease
$(".myClass").animate({top:100, left:200}, {duration:3000, easing:"easeOutStrong"});

//tween width to 50% and then height to 200px (sequenced) and then call myFunction
$(".myClass").animate({width:"50%"}, 2000).animate({height:"200px"}, {duration:3000, complete:myFunction});

See jQuery's API docs for details about the syntax and options available with the animate() method. And yes, the jQuery.stop() method works too.

Caveats

1. If you define any of the following in the animate() call, it will revert to the native jQuery.animate() method in order to maximize compatibility (meaning no GSAP speed boost and no GSAP-specific special properties will work in that particular call):
   • a "step" function - providing the parameters to the callback that jQuery normally does would be too costly performance-wise. One of the biggest goals of GSAP is optimized performance; We'd strongly recommend NOT using a "step" function for that reason. Instead, you can use an onUpdate if you want a function to be called each time the values are updated.
   • Anything with a value of "show", "hide", "toggle", "scrollTop" or "scrollLeft". jQuery handles these in a unique way and we don't want to add the code into CSSPlugin that would be required to support them natively in GSAP.
   • If skipGSAP:true is found in the "properties" parameter, it will force things to fall back to the native jQuery.animate() method. So if a particular animation is acting different than what you're used to with the native jQuery.animate() method, you can just force the fallback using this special property. Like $(".myClass").animate({scrollTop:200, skipGSAP:true});
2. This is our first crack at a jQuery plugin, so please let us know if anything breaks or if you have ideas for improvement.