Getting Started

To use the Animation utility, include the following source files in your web page with the script tag:

<!-- Dependencies --> <script src="http://yui.yahooapis.com/2.5.2/build/yahoo-dom-event/yahoo-dom-event.js" type="text/javascript"></script> <!-- Source file --> <script src="http://yui.yahooapis.com/2.5.2/build/animation/animation-min.js" type="text/javascript"></script>

Your Animation implementation will consist of one or more instances of the Anim object or its subclasses (Motion, Scroll).

Instantiating an Animation Object

To create an Animation instance on your page, use the following code:

<div id="test"></div> <script> var myAnim = new YAHOO.util.Anim('test', { width: { to: 400 } }, 1, YAHOO.util.Easing.easeOut); </script>

The Anim object constructor has one required parameter: the ID string or element reference to the element that will be animated. Optional parameters are:

• the actual attribute(s) that will comprise the animation (required to see any actual animation occur)
• the duration of the animation (defaults to 1 second)
• the easing method (defaults to YAHOO.util.Easing.easeNone)

We'll explore the optional parameters in more detail later in this document.

To initiate the actual animation, call the animate method on your Animation instance:

myAnim.animate();

Setting Animation Properties

In addition to passing detailed arguments to the Anim constructor, you can set the other parameters on your Animation instance via their respective properties:

var myAnim = new YAHOO.util.Anim('test'); myAnim.attributes.width = { to: 400 }; myAnim.duration = 0.5; myAnim.method = YAHOO.util.Easing.easeOut;

See the API documentation for the Anim object for more information about its methods and properties.

Using Animation

This section describes how to use the Animation utility in further detail. It contains these subsections:

• Using Animation Attributes
• Using Relative Values
• Setting a Starting Value
• Specifying Attribute Units
• Listening for Events
• Creating Animation with Motion
• Creating Animation with Motion along a Curve
• Creating Animation with Scroll

Using Attributes

An attributes object is required to tell the Animation instance what to animate. The members of this object comprise one or more style properties that accept a numeric value (width, height, opacity, top, left, borderWidth, padding, margin, and so on).

An attribute consists of the attribute name ("width", for example) and the value at which the animation should end, specified with the "to" or "by" properties. By default, the Animation will attempt to start from the current value, although in some cases, this is not as reliable as providing the starting value explicitly (with the "from" property).

The following code animates an element from its current size to 400 by 400:

var attributes = { width: { to: 400 }, height: { to: 400 } }; var myAnim = new YAHOO.util.Anim('test', attributes); myAnim.animate();

Using Relative Values

To animate an element by a given value rather than to a given value, use the "by" property, rather than "to".

The following will expand the element with the id of test from its current size by 200 pixels:

var attributes = { width: { by: 200 }, height: { by: 200 } }; var myAnim = new YAHOO.util.Anim('test', attributes); myAnim.animate();

Setting a Starting Value

Use the optional "from" attribute property to start the animation from a specific size:

var attributes = { width: { from: 10, by: 200 }, height: { from: 10, by: 200 } }; var myAnim = new YAHOO.util.Anim('test', attributes); myAnim.animate();

Specifying Attribute Units

By default, all attributes (except opacity) use pixels as the unit of measurement. You can override this with the "unit" property.

The following will animate the element's size from 1 to 20 EMs:

var attributes = { width: { from: 1, to: 20, unit: 'em' }, height: { from: 1, to: 20, unit: 'em' } }; var myAnim = new YAHOO.util.Anim('test', attributes); myAnim.animate();

Listening for Events

The Animation utility defines three events: onStart, onTween, and onComplete. Each of these events expose a subscribe method, enabling you to bind a callback function to that event.

The following will remove the animated element (whose HTML ID is test) from its parent node upon completion of the animation:

var removeElement = function() { var el = this.getEl(); el.parentNode.removeChild(el); } var myAnim = new YAHOO.util.Anim('test', { height: {to: 10} }, 1, YAHOO.util.Easing.easeOut); myAnim.onComplete.subscribe(removeElement); myAnim.animate();

To avoid any potential race conditions, events should be subscribed to prior to calling the animate method.

Animating with ColorAnim

The YAHOO.util.ColorAnim subclass extends the Anim base class to allow animation of colors, including background, border, and color. Colors can be specified either as hex or rgb.

The following creates a ColorAnim animation that changes the background color of the element from its current background color to "#dcdcdc":

var element = document.getElementById('test'); var myAnim = new YAHOO.util.ColorAnim(element, {backgroundColor: { to: '#dcdcdc' } }); myAnim.animate();

Creating Animation with Motion

The YAHOO.util.Motion subclass extends the ColorAnim class to move the animated element along a set of points. Points are defined by arrays of x,y coordinates.

The following creates a Motion animation that moves from its current position to [400, 400] in page coordinates:

var myAnim = new YAHOO.util.Motion('test', {points: { to: [400, 400] } }); myAnim.animate();

Creating Animation with Motion along a Curve

The YAHOO.util.Motion class also provides for curved animations. A curve can be defined by one or more control points. Control points are added to the points attribute via the "control" property.

The following creates a Motion animation in which the animated element moves along a curved path from its current position to [400, 400]; the curved path is defined by two control points:

var attributes = { points: { to: [400, 400], control: [[800, 300], [-200, 400]] } }; var myAnim = new YAHOO.util.Motion('test', attributes); myAnim.animate();

Creating Animation with Scroll

Like Motion, The YAHOO.util.Scroll subclass extends the ColorAnim class to scroll an overflowed element. Scroll values are defined as arrays of scrollTop and scrollLeft values.

The following creates a Scroll animation that scrolls the element left from its current left-scroll position to 500:

var element = document.getElementById('test'); var myAnim = new YAHOO.util.Scroll(element, { scroll: { to: [500, test.scrollTop] } }); myAnim.animate();

YUI on Mobile: Using Animation Utility with "A-Grade" Mobile Browsers

Animation on mobile devices is limited by processor and system overhead. Even on PCs, animation within a web browser can tax the processor, and the processing power in mobile devices is much more limited. In general, DOM animations will look choppy on a mobile device, so you may want to avoid them altogether if designing specifically for mobile. Using an easing method in some cases helps to make the animation appear to run more smoothly. On the iPhone specifically, the "easeBoth" easing, in our experience, provides the smoothest animation across most animation types.

Support & Community

The YUI Library and related topics are discussed on the on the ydn-javascript mailing list.

In addition, please visit the YUIBlog for updates and articles about the YUI Library written by the library's developers.

Filing Bugs & Feature Requests

The YUI Library's public bug tracking and feature request repositories are located on the YUI SourceForge project site. Before filing new feature requests or bug reports, please review our reporting guidelines.

• Guidelines for YUI feature requests and bug reports.
• Review current bug list or file a new bug.
• Review current feature requests or file a new feature request.