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!

jQuery.animate() with GSAP

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

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:

  • Twitter
  • Facebook
  • Digg
  • StumbleUpon
  • del.icio.us
  • Yahoo! Buzz
  • Google Bookmarks
  • RSS
  • LinkedIn
  • Reddit

Comments (19) RSS

Posted by jermbo on January 27, 2013

just wow! you kill it yet again!!

Posted by Farzan Mohajerani on January 29, 2013

Thank you for your great plugin. This is what I exactly needed for my latest project. I’m using jquery Isotope too animating heavy scale elements in my page and I could not change the animate function manually. You could not imagine how much this plugin improve my animation.
I tested it, but the only problem is my scroll animation stopped working.
I still didn’t checked it out that where the problem is, but I’m sure that this one is too gonna solve.

Posted by Farzan Mohajerani on January 29, 2013

Hi. Thanks for your quick reply.
I found that first of all I didn’t import the ScrollToPlugin as I thought TweenMax has all the GSAP plugins.
But the problem was still there. I found that the selector object for scrolling the whole page in GSAP is different from jQuery.
I used $(‘html,body’).animate({scrollTop:destY}); for scrolling the page. But It could not transform it GSAP.
I even used these solutions :
(1) :
To see if it transform it individually.
$(‘html’).animate({scrollTop:destY});
$(‘html’).animate({scrollTop:destY});

(2) :
To see if it just works with TweenMax or not.
TweenMax.to($(‘html’),0.3,{scrollTop:destY});
TweenMax.to($(‘body’),0.3,{scrollTop:destY});

None of above solutions worked for me.
At last I decided to not wait for the jquery.gsap plugin to transform my animation (in just this particular subject “Scrolling” the page) and simply just used this :
TweenMax.to(window,0.3,{scrollTo:{y:destY}});

Problem solved :D
I don’t know if it’s me that missing something or that’s the only way to do it.

Thank you

Posted by Jack on January 29, 2013

Farzan, I think you probably meant to do this:

$(window).animate({scrollTo:destY});

Just make sure you load the ScrollToPlugin as well (as you discovered). We don’t include ALL plugins in TweenMax because I fear it’ll just get too big as we come out with more and more plugins. So we cover a lot of the common basics inside TweenMax.

Posted by Peter_D on February 1, 2013

Wow, big jump. Congratulations.

Posted by Lefthandmedia on February 5, 2013

Hi,

which would be faster?
$(“#myDiv”).animate({top:100, left:200},2000);
or
TweenLite.to(“#myDiv”, 2, {top:100, left:200});

Posted by Jack on February 5, 2013

The native TweenLite method(s) would be slightly faster just because there’s less parsing required (it doesn’t have to translate the jQuery.animate() data into GSAP format). See FAQ 2.

Posted by Gio on February 11, 2013

The best animation platform in the world! Thanks for your hard work! You rock the world of web (and not only) animation!

Posted by Justin on February 11, 2013

Looking forward to giving this a whirl! Have you noticed any browser compatibility issues that should be noted?

Posted by Jack on February 11, 2013

No, Justin, we’re not aware of any browser compatibility issues at this point. Let us know if you find something, though.

Posted by Marktastic on February 12, 2013

I don’t suppose you could update the speed comparison test to have a jQuery animate + GSAP option? That’d be awesome!

Posted by Jack on February 13, 2013

Sure, jquery.gsap.js was just added to the speed test. Enjoy!

http://www.greensock.com/js/speed.html

Posted by mel on February 14, 2013

Anyone tried this with Adobe Edge (with timeline not code animations)?

great work jack!

Posted by Filip on February 15, 2013

Hi all. I’ve got 2 questions:

1. Is this plugin work only for jquery animate function? Or work with other jquery functions too? (scroll to, hide/show, fade…)

2. In which order should I load libraries? In example I have: gsap files, jquery, jquery libraries, other libraries like nice scroll or flexslider

Posted by Jack on February 15, 2013

1) It works on anything that flows through the jQuery.animate() method except things that use jQuery-specific “show”, “hide”, “toggle”, (actualy, “scrollTop” and “scrollLeft” too because jQuery handles them in a non-standard way).

2) As long as you load jQuery before the plugin, you should be fine. GreenSock files themselves have code in place that handles loading them in any order, but since the jquery.gsap.js plugin builds on jQuery, jQuery must be loaded first.

Posted by ace on February 20, 2013

Does it support -= and += to animate values relatively? I can’t seem to make that work.

Also I used skewX and in IE 6/7/8 the element seemed to try to skew but it was clipped inside a container.

Posted by Jack on February 20, 2013

Yes, ace, it definitely supports +=/-= relative values. And the skew clipping you saw in IE6-8 is because you didn’t set position to absolute (old versions of IE force the clipping otherwise). If you’re still having trouble, please don’t hesitate to post in the forums at http://forums.greensock.com. I’d love to see a sample codepen/jsfiddle/file that demonstrates the problem(s). I just tested the +=/-= relative stuff and it worked as expected. Make sure you’re using the latest version of the GSAP files too.

Posted by ace on February 27, 2013

the +=/-= problem was that I was e.g. using “-=20px” instead of “-=20″

Also could this plugin be expanded to include the jquery .css() function?
It could be useful for resetting CSS transition/box-shadow etc. properties without having to do animate() with 1 msec.

Posted by Jack on February 27, 2013

ace, it’s fine to use units in the relative values, like “-=20px”. I’d be curious to see an example of where that wasn’t working for you.

As for including the jQuery.css() function, that’s tricky because it would have to provide “get” capabilities too (not just “set”) for everything, and that can be non-trivial when dealing with special stuff like individual transforms (scaleX/scaleY/x/y/z/rotation/rotationX/etc.), or things like scrollTo, etc. And then there’s the fact that jQuery has some special properties that it handles in a unique way too, so it’s not as easy as just feeding stuff to GSAP. We’ll definitely keep this in mind as a potential future enhancement though. It isn’t impossible, for sure. We appreciate the feedback/suggestion.

To download the code, you must agree to the following license:

"NO CHARGE" NON-EXCLUSIVE SOFTWARE LICENSE AGREEMENT
-----------------------------------------------------------------------------
PLAIN ENGLISH SUMMARY:

  1. You may use the code at no charge in commercial or non-commercial apps, web sites, games, components, and other software as long as end users are not charged a fee of any kind to use your product or gain access to any part of it. If your client pays you a one-time fee to create the site/product, that's perfectly fine and qualifies under the "no charge" license. If end users are charged a usage/access/license fee, please sign up for a "Business Green" Club GreenSock membership which comes with a comprehensive commercial license. See http://www.greensock.com/club/ for details.
  2. Use at your own risk. No warranties are offered.
  3. Please respect the copyright.

-----------------------------------------------------------------------------

LEGALESE:

This is a legal agreement between you (either an individual or a single entity) and GreenSock, Inc. ("GREENSOCK") for the proprietary GreenSock code known as TweenLite, TweenMax, TweenNano, TimelineLite, TimelineMax, and other copyrighted code that is available for download at http://www.greensock.com (this code and documentation, as well as any updates which may at GREENSOCK's sole discretion be provided to you from time to time, are referred to in this Agreement as "PROGRAM"). By downloading, copying, or otherwise using the PROGRAM, you agree to the terms and conditions of this Agreement. If you do not agree to the terms and conditions of this Agreement, please do not download or use the PROGRAM.

I. LICENSE
A. Subject to the terms and conditions of this Agreement, GREENSOCK hereby grants you a non-exclusive, worldwide, non-transferable right to use the PROGRAM in apps, web sites, games, components and other software applications ("Developed Works") for which the end user is NOT charged any fees. If you would like to use the code in a commercially licensed Developed Work for which end users are charged a fee (either for usage or access), simply sign up for the appropriate "Business Green" Club GreenSock membership at http://www.greensock.com/club/.

II. LIMITATION OF LICENSE AND RESTRICTIONS
A. You agree that you will not sell, rent, or license the PROGRAM's source code or any derivative works thereof to any third party without the prior written consent of GREENSOCK. Distribution of the PROGRAM as part of your Developed Work is acceptable so long as it is used exclusively as a part of your Developed Work. You agree not to modify or delete GREENSOCK'S existing copyright notices located in the source code.

B. You may use, duplicate, and distribute the compiled object code as embedded in Developed Works created by you, either for your own use or for distribution to a third party so long as end users of the Developed Work are not charged a fee for usage of or access to any portion of the Developed Work. Please see http://www.greensock.com/licensing/ for descriptions of Developed Works that qualify for the "No Charge" license.

C. You may make modifications to the source code exclusively for your own use in order to perform bug fixes or other minor edits required to operate the PROGRAM as originally intended.

III. CONSIDERATION
A. The license rights granted to you under this Agreement are at no charge, but only in the following circumstances: If on your own behalf or on behalf of a third party you incorporate the PROGRAM into a web site, app, game, program or any component thereof (collectively, "Developed Work"), which in the case of a web site, must be accessible to internet users without payment of a fee of any kind, and in the case of a software application, game, program or component, neither you nor anyone to whom you distribute the Developed Work charges a user a fee of any kind to use such Developed Work or application, game, program or component into which such Developed Work is embedded. The foregoing shall apply regardless of whether you are paid to create such Developed Work.

B. In the event your intended use of the PROGRAM does not meet the criteria for the "no charge" license rights set forth in the immediately preceding paragraph, then you are not licensed to use the PROGRAM under this Agreement and must license the PROGRAM under GREENSOCK'S separate fee-based Software License Agreement which is granted to "Business Green" Club GreenSock members (see http://www.greensock.com/club/ for details).

C. You may make modifications to the source code exclusively for your own use in order to perform bug fixes or other minor edits required to operate the PROGRAM as originally intended.

IV. TITLE AND OWNERSHIP
A. The PROGRAM is licensed, not sold, and is protected by copyright laws and international treaty provisions. You acknowledge that no title to the intellectual property in the PROGRAM is transferred to you. You further acknowledge that title and full ownership rights to the PROGRAM, including all intellectual property rights therein, will remain the exclusive property of GREENSOCK and you will not acquire any rights to the PROGRAM except as expressly set forth in this Agreement. You agree that any copies of the PROGRAM you make will contain the same proprietary notices which appear on and in the PROGRAM. You agree that GREENSOCK may identify you as a licensee unless you make a written request otherwise. GREENSOCK hereby grants to you the right to disclose that your product, game, software application, component, or other Developed Work makes use of GREENSOCK code (for example, "Powered by TweenLite").

V. DISCLAIMER OF WARRANTY AND LIMITATION OF LIABILITY
A. THE PROGRAM IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. GREENSOCK DOES NOT WARRANT THAT THE FUNCTIONS CONTAINED IN THE PROGRAM WILL MEET YOUR REQUIREMENTS OR THAT OPERATION WILL BE UNINTERRUPTED OR ERROR FREE. GREENSOCK shall not be liable for special, indirect, incidental, or consequential damages with respect to any claim on account of or arising from this Agreement or use of the PROGRAM, even if GREENSOCK has been or is hereafter advised of the possibility of such damages. Because some states do not allow certain exclusions or limitations on implied warranties or of liability for consequential or incidental damages, the above exclusions may not apply to you. In no event, however, will GREENSOCK be liable to you, under any theory of recovery, in an amount in excess of $250. Notwithstanding anything else in this agreement, you agree to indemnify GREENSOCK, its assignees, and licensees, and hold each of them harmless from and against any and all claims, losses, damages, and expenses, including legal fees arising out of or resulting from any negligent act or omission by you.

B. GREENSOCK may, at its sole discretion, provide support services related to the PROGRAM, but has no obligation to do so.

VI. TERMINATION
If you at any time fail to abide by the terms of this Agreement, GREENSOCK shall have the right to immediately terminate the license granted herein and pursue any other legal or equitable remedies available.

VII. MISCELLANEOUS
A. This Agreement shall be construed in accordance with the laws of the State of Illinois. In the event of any dispute between you and GREENSOCK with respect to this Agreement, we both agree that if we cannot resolve the dispute in good faith discussion, either of us may submit the dispute for resolution to arbitration with the American Arbitration Association before a single arbitrator using the AAA Rules for Commercial Arbitration. The arbitrator's decision is final and can be enforced in any court with jurisdiction over such matters.

B. This agreement represents the complete and exclusive statement of the agreement between GREENSOCK and you and supersedes all prior agreements, proposals, representations and other communications, verbal or written, between them with respect to use of the program. This agreement may be modified only with the mutual written approval of authorized representatives of the parties.

C. The terms and conditions of this Agreement shall prevail notwithstanding any different, conflicting, or additional terms or conditions which may appear in any purchase order or other document submitted by you. You agree that such additional or inconsistent terms are deemed rejected by GREENSOCK.

D. GREENSOCK and you agree that any xerographically or electronically reproduced copy of this Agreement shall have the same legal force and effect as any copy bearing original signatures of the parties.

Copyright 2006-2013, GreenSock, Inc. Updated 2012-08-28

I'd like to learn how to get bonus plugins, update notifications, SVN access, and more.
To continue, you must agree to the following license: