jQuery.animate() with GSAP? Introducing jquery.gsap.js plugin

t

t

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 type="text/javascript" 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.

FAQ

1. Do I have to learn the GSAP API in order to use this plugin? I don’t want to learn another API. I love jQuery.
   Nope, you don’t have to worry your pretty little head about learning the GSAP API if you don’t want to. Just load the plugin and animate() the way you always have. However, if you take the time to learn the native GSAP API, it could revolutionize your animation workflow in some surprising ways. If you’re doing anything beyond very basic tweens, it’s probably worth your time. But there’s no pressure.
2. If I already know the GSAP API, is it better to use jQuery.animate() or the standard GSAP methods like TweenLite.to()?
   Using jQuery.animate() is fine for basic stuff, but we would definitely recommend using the native GSAP methods whenever you can because they’re slightly faster (no extra parsing) and they make experimenting and building sequences much easier, plus they’re object-oriented so you can pause()/resume()/reverse()/restart()/seek() individual tweens or entire timelines. You can even nest timelines within timelines.
3. Can I define the ease in the standard jQuery way, like “easeOutStrong” and “linear” and “swing”?
   Absolutely, please do.
4. Can I get the tween instances so that I can control them individually?
   No, not from the animate() method – if you want to get precise control like that, please use the regular GSAP API. The jQuery.animate() method only returns a jQuery object and it taps into an internal queue system for sequencing that would get circumvented if you manually paused or reversed the tweens. The plugin is only intended to duplicate the native functionality plus add extra tweenable properties and speed things up of course.
5. When features get added to GSAP, will this plugin get updated?
   The plugin is just a harness that takes whatever you give jQuery.animate() and feeds the data to GSAP under the hood, so yes, when you update your GSAP files you’ll instantly get the new features.
6. Can I use other GSAP plugins like ScrollToPlugin with jQuery.animate()?
   Yes, as long as you loaded the plugin you can use it. For example:

   $(window).animate({scrollTo:{y:300}}, 3000);
   			

7. Is there a way to disable/enable this plugin’s functionality? In other words, what if the plugin is loaded and GSAP isn’t animating something properly and I want to revert to using the native jQuery.animate() method?
   Yes:

   //disables GSAP from all jQuery.animate() calls:
   $.gsap.enabled(false);
   
   //enables it again:
   $.gsap.enabled(true);
   
   //disables GSAP only in a particular animate() call:
   $(".myClass").animate({left:100, skipGSAP:true}, 2000);
   			

Stay up to date

We’d highly recommend checking back frequently and keeping your files updated because we’re constantly adding features, patching bugs, implementing workarounds for new browser inconsistencies, etc. Sign up for a free GreenSock account so that you’re on our mailing list and get important notifications. Don’t forget to follow us on Twitter as @greensock and Facebook too.

Need help?

There are dedicated forums for all GreenSock tools at http://forums.greensock.com/. Keep in mind that you’ll increase your chances of getting a prompt answer if you provide a brief explanation and include a simplified HTML file (and any dependencies) that clearly demonstrates the problem with as little code as possible.

Recommended reading:

• Main GSAP JS page (with downloads)
• Jump Start: GSAP JS
• jQuery vs GSAP: cage match
• Speed comparison
• 3D Transforms & More CSS3 Goodies Arrive in GSAP JS
• jQuery.animate() docs

Comments (19)

Subscribe