Package	com.greensock.plugins
Class	public class CSSPlugin
Inheritance	CSSPlugin TweenPlugin Object

//notice the css-related values are inside the "css" object but the ease is not:
TweenLite.to(element, 1, {css:{top:"20px", left:"100px", backgroundColor:"#FF0000"}, ease:Power2.easeOut});

Note: a common mistake is to forget to wrap css-related properties in a css object which is essential for specifying your intent. Remember, GSAP (GreenSock Animation Platform) isn't just for tweening css properties. And always use camel case representations of the properties, so instead of "font-size", you'd use "fontSize".

To get up and running quickly with GSAP, check out the Jump Start tour which covers the basics in a fun, interactive way. To see the CSS3-specific features (like 3D transforms, boxShadow, textShadow, borderRadius, and clip) demonstrated and explained, see http://www.greensock.com/css3/.

You can even define properties that are not generally tweenable and GSAP will apply the property for you (like position:"absolute" or borderStyle:"solid"). These non-tweenable properties will be set at the beginning of the tween (except display:"none" which will be applied at the end of the tween for obvious reasons).

It is typically a good idea to define a unit of measurement (like "24px" instead of "24" or "50%" rather than "50") but the default in most cases is pixels (px), so you can omit the unit if you prefer. In fact, you can define your own defaults using the CSSPlugin.suffixMap object. And even if the unit of measurement doesn't match the current one, GSAP will attempt to convert them for you. So, for example, you could tween a width from "50%" to "200px".

CSSPlugin can even animate complex values like boxShadow:"0px 0px 20px 20px red" and borderRadius:"50% 50%" and border:"5px solid rgb(0,255,0)" . When necessary, it attempts to figure out if the property needs a vendor prefix and applies it accordingly. There may be a small subset of complex or bleeding-edge css properties that CSSPlugin can't handle yet, but the vast majority work great.

In addition to almost all of the standard css properties, CSSPlugin recognizes some special ones that can be quite convenient:

• 2D transforms: rotation, scaleX, scaleY, scale, skewX, skewY, x, and y - one of the most convenient things about the CSSPlugin is that it greatly simplifies transforms in the various browsers including IE back through version 6! No need to mess with various browser prefixes or funky matrix filters in IE. You can animate 2D transform properties inuitively:

  //much simpler
  TweenLite.to(element, 2, {css:{rotation:30, scaleX:0.8}});
  

  By default, rotation, skewX, and skewY use degrees but you can use radians if you prefer. Simply append one of the standard suffixes ("rad" or "deg") like this:

  //use "deg" or "rad"
  TweenLite.to(element, 2, {css:{rotation:"1.25rad", skewX:"30deg"}});
  

  To be clear, this is like setting the element's css to: transform:rotate(1.25rad) skewX(30deg) along with all the other browser prefix values and the necessary IE filter which would be much more verbose. And CSSPlugin will affect the skewX/skewY values in a slightly different (arguably more intuitive) way than some browsers because visually the object isn't stretched. For example, if you set transform:skewX(85deg) in the browser via CSS, the object would become EXTREMELY long (stretched) whereas with CSSPlugin, it would look more like it sheared in 3D space. Again this was a purposeful design decision because this behavior is more likely what animators desire. You can certainly get the same effect as the default browser behavior by tweening the scaleX/scaleY accordingly, using trigonometry.

  Notes about 2D transforms:

  1. It is typically best to set the element's position to "absolute" to avoid clipping in the browsers.
  2. You can use "scale" as a shortcut to control both the "scaleX" and "scaleY" properties identically.
  3. You can define relative values, like rotate:"+=30deg"
  4. The order in which you declare the transform properties makes no difference.
  5. If your goal is to animate the x/y position of the element, browsers seem to perform slightly better if you just animate the regular "top" and "left" properties instead of "x" and "y".
  6. TweenLite has nothing to do with the rendering quality of the element in the browser. Some browsers seem to render transformed elements beautifully while others don't handle anti-aliasing as well.
  7. IE6, IE7, and IE8 transforms don't apply to child elements (it's a browser limitation).
• 3D transforms: in addition to all of the regular 2D properties (x, y, scaleX, scaleY, scale, rotation, skewX, and skewY) that work in almost all browsers, you can animate 3D properties too like rotationX, rotationY, rotationZ (identical to regular "rotation"), z, perspective, and transformPerspective in most modern browsers (see http://caniuse.com/transforms3d for details about browser support for 3D transforms). To see 3D transforms demonstrated visually in GSAP, see http://www.greensock.com/css3/. Again, there is no need to use browser prefixes; CSSPlugin handles all of that for you under the hood. You can animate 3D transform properties and 2D properties (except skew) together inuitively:

  TweenLite.to(element, 2, {css:{rotationX:45, scaleX:0.8, z:-300}});
  

  To get your elements to have a true 3D visual perspective applied, you must either set the "perspective" property of the parent element or set the special "transformPerspective" of the element itself (common values range from around 200 to 1000, the lower the number the stronger the perspective distortion). The "transformPerspective" is like adding a perspective() directly inside the css "transform" style, like: transform:perspective(500px) rotateX(45deg) which only applies to that specific element whereas if you want to a group of elements share a common perspective (the same vanishing point), you should set the regular "perspective" property on the parent/container of those elements. For more information about perspective, see this article.

  //apply a perspective to the PARENT element (the container) to make the perspective apply to all child elements (typically best)
  TweenLite.set(container, {css:{perspective:500}});
  
  //or set a default perspective that will be applied to every individual element that you tween in 3D:
  CSSPlugin.defaultTransformPerspective = 500;
  
  //or apply perspective to a single element using "transformPerspective"
  TweenLite.set(element, {css:{transformPerspective:500}});
  

  In regular CSS, the order that you list the transforms matters but GSAP always applies them in the same order for consistency: scale, then rotation (same as rotationZ), then rotationY, then rotationX, then translation (x, y, z). If you want to rotate the element around a point in 3D space other than its center, use the transformOrigin property (see below).

  //sample css:
  .myClass {
      transform: scale(1.5, 1.5) rotateY(45deg) translate3d(10px, 0px, -200px)
  }
   
  //corresponding GSAP transform (tweened over 2 seconds):
  TweenLite.to(element, 2, {css:{scale:1.5, rotationY:45, x:10, y:0, z:-200}});
  
  //sample css that uses a perspective():
  .myClass {
      transform: perspective(500px) rotate(120deg) translateY(50px)
  }
  
  //corresponding GSAP transform (set, not tweened):
  TweenLite.set(element, {css:{transformPerspective:500, rotation:120, y:50}});
  

  Notes about 3D transforms:

  1. In browsers that don't support 3D transforms, they'll be ignored. For example, rotationX may not work, but rotation would. See http://caniuse.com/transforms3d for a chart of which browser versions support 3D transforms.
  2. All transforms are remembered, so you can tween individual properties without worrying that they'll be lost. You don't need to define all of the transform properties on every tween - only the ones you want to animate.
  3. TweenLite has nothing to do with the rendering quality of the element in the browser. Some browsers seem to render transformed elements beautifully while others don't handle anti-aliasing as well.
  4. To learn more about css 3D transforms, see this article
  5. IE10 supports 3D transforms, but it does not support transformStyle of "preserve-3d" (see Microsoft's site for details).
• transformOrigin - Sets the origin around which all transforms (2D and/or 3D) occur. By default, it is in the center of the element ("50% 50%"). You can define the values using the keywords "top", "left", "right", or "bottom" or you can use percentages (bottom right corner would be "100% 100%") or pixels. If, for example, you want an object to spin around its top left corner you can do this:

  //spins around the element's top left corner
  TweenLite.to(element, 2, {css:{rotation:360, transformOrigin:"left top"}});
  

  The first value in the quotes corresponds to the x-axis and the second corresponds to the y-axis, so to make the object transform around exactly 50px in from its left edge and 20px from its top edge, you could do:

  //spins/scales around a point offset from the top left by 50px, 20px
  TweenLite.to(element, 2, {css:{rotation:270, scale:0.5, transformOrigin:"50px 20px"}});
  

  You can define a transformOrigin as a 3D value by adding a 3rd number, like to rotate around the y-axis from a point that is offset 400px in the distance, you could do:

  //rotates around a point that is 400px back in 3D space, creating an interesting effect:
  TweenLite.to(element, 2, {css:{rotationY:360, transformOrigin:"50% 50% -400px"}});
  

  Notes about transformOrigin:

  1. CSSPlugin automatically works around a bug in Safari that causes 3D transformOrigin values to incorrectly act as though they affect translateZ(). To work around the bug, when you perform a 3D tween that has a transformOrigin with a non-zero z component (like transformOrigin:"50% 50% -100px"), CSSPlugin will record the z-component (-100px in this example) internally and remove it from the transformOrigin that gets applied to the css. Everything will render correctly because the z-axis origin offset is calculated internally and applied to the matrix3d(). Just keep in mind that if you check the css value of the transformOrigin after the tween has started, it won't have the z component but that's by design.
  2. transformOrigin even works in Internet Explorer back to version 6 in 2D, although it is recommended that you set the element's position to "absolute" to avoid clipping.
• shortRotation - tweens the rotation property in the shortest direction. For example, if the element's rotation is currently 170 degrees and you want to tween it to -170 degrees, a normal rotation tween would travel a total of 340 degrees in the counter-clockwise direction, but if you use shortRotation, it would travel 20 degrees in the clockwise direction instead. Example:

  TweenLite.to(element, 2, {css:{shortRotation:-170}});

  For 3D rotations, you may also use shortRotationX and shortRotationY.
• autoAlpha - the same thing as "opacity" except that when the value hits "0", the "visibility" property will be set to "hidden" in order to improve browser rendering performance and prevent clicks/interactivity on the target. When the value is anything other than 0, "visibility" will be set to "visible". And if the element's visibility is initially set to "hidden" and opacity is 1, it will assume opacity should also start at 0. This makes it simple to start things out on your page as invisible (set your css visibility:hidden) and then fade them in whenever you want.

  //fade out and set visibility:hidden
  TweenLite.to(element, 2, {css:{autoAlpha:0}});
  
  //in 2 seconds, fade back in with visibility:visible
  TweenLite.to(element, 2, {css:{autoAlpha:1}, delay:2});
  

• className - allows you to morph between classes on an element. For example, let's say myElement has a class of "class1" currently and you want to change to "class2" and animate the differences, you could do this:

  TweenLite.to(myElement, 1, {css:{className:"class2"}});

  And if you want to ADD the class to the existing one, you can simply use the "+=" prefix. To remove a class, use the "-=" prefix like this:

  TweenLite.to(myElement, 1, {css:{className:"+=class2"}});

  Note: there are some css-related properties that don't tween like IE filters and 3D transforms (support for those may come in the future). Also, there is a slight speed penalty when using className because the engine needs to loop through all of the css properties to see which ones are different.

• bezier - Animate virtually any property (or properties) along a Bezier (curved) path which you define as an array of points/values that can be interpreted in several different ways, like as points through which a Bezier should be drawn, or cubic or quadratic Bezier control and anchor points, etc. See the BezierPlugin's documentation for details and an explanation of all the features available. Don't forget to load the BezierPlugin JavaScript file in order to utilize its features from within CSSPlugin. Here is an example of a bezier tween that makes an element curve through 3 points using x and y transform properties and also automatically rotates it along the path as it goes:

  TweenLite.to(element, 5, {css:{bezier:{curviness:1.25, values:[{x:100, y:200}, {x:250, y:400}, {x:500, y:50}], autoRotate:true}}, ease:Power1.easeOut});

• autoRound - By default, CSSPlugin will round pixel values and zIndex to the closest integer during the tween (the inbetween values) because it improves browser performance, but if you'd rather disable that behavior, pass autoRound:false in the css object. You can still use the RoundPropsPlugin to manually define properties that you want rounded.

Copyright 2008-2012, GreenSock. All rights reserved. This work is subject to the terms in http://www.greensock.com/terms_of_use.html or for Club GreenSock members, the software agreement that was issued with the membership.