YUI recommends YUI3.

YUI 2 has been deprecated since 2011. This site acts as an archive for files and documentation.

This documentation is no longer maintained.

YUI 2: Animation

YUI 2: Animation

The Animation Utility enables the rapid prototyping and implementation of animations involving size, opacity, color, position, and other visual characteristics. Animations created with the Animation Utility work across the A-grade browser spectrum. A simple, intuitive syntax for configuring animations makes the Animation Utility easy to implement even for complex animations.

Getting Started

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

  1. <!-- Dependencies -->
  2. <script src="http://yui.yahooapis.com/2.9.0/build/yahoo-dom-event/yahoo-dom-event.js" type="text/javascript"></script>
  3.  
  4. <!-- Source file -->
  5. <script src="http://yui.yahooapis.com/2.9.0/build/animation/animation-min.js" type="text/javascript"></script>
  6.  
<!-- Dependencies -->
<script src="http://yui.yahooapis.com/2.9.0/build/yahoo-dom-event/yahoo-dom-event.js" type="text/javascript"></script>
 
<!-- Source file -->
<script src="http://yui.yahooapis.com/2.9.0/build/animation/animation-min.js" type="text/javascript"></script>
 

YUI dependency configurator.

YUI Dependency Configurator:

Instead of copying and pasting the filepaths above, try letting the YUI dependency Configurator determine the optimal file list for your desired components; the Configurator uses YUI Loader to write out the full HTML for including the precise files you need for your implementation.

Note: If you wish to include this component via the YUI Loader, its module name is animation. (Click here for the full list of module names for YUI Loader.)

Where these files come from: The files included using the text above will be served from Yahoo! servers. JavaScript files are minified, meaning that comments and white space have been removed to make them more efficient to download. To use the full, commented versions or the -debug versions of YUI JavaScript files, please download the library distribution and host the files on your own server.

Order matters: As is the case generally with JavaScript and CSS, order matters; these files should be included in the order specified above. If you include files in the wrong order, errors may result.

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:

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

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:

  1. myAnim.animate();
  2.  
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:

  1. var myAnim = new YAHOO.util.Anim('test');
  2. myAnim.attributes.width = { to: 400 };
  3. myAnim.duration = 0.5;
  4. myAnim.method = YAHOO.util.Easing.easeOut;
  5.  
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 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:

  1. var attributes = {
  2. width: { to: 400 },
  3. height: { to: 400 }
  4. };
  5.  
  6. var myAnim = new YAHOO.util.Anim('test', attributes);
  7. myAnim.animate();
  8.  
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:

  1. var attributes = {
  2. width: { by: 200 },
  3. height: { by: 200 }
  4. };
  5.  
  6. var myAnim = new YAHOO.util.Anim('test', attributes);
  7. myAnim.animate();
  8.  
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:

  1. var attributes = {
  2. width: { from: 10, by: 200 },
  3. height: { from: 10, by: 200 }
  4. };
  5.  
  6. var myAnim = new YAHOO.util.Anim('test', attributes);
  7. myAnim.animate();
  8.  
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:

  1. var attributes = {
  2. width: { from: 1, to: 20, unit: 'em' },
  3. height: { from: 1, to: 20, unit: 'em' }
  4. };
  5.  
  6. var myAnim = new YAHOO.util.Anim('test', attributes);
  7. myAnim.animate();
  8.  
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:

  1. var removeElement = function() {
  2. var el = this.getEl();
  3. el.parentNode.removeChild(el);
  4. }
  5. var myAnim = new YAHOO.util.Anim('test', {
  6. height: {to: 10}
  7. }, 1, YAHOO.util.Easing.easeOut);
  8. myAnim.onComplete.subscribe(removeElement);
  9. myAnim.animate();
  10.  
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":

  1. var element = document.getElementById('test');
  2. var myAnim = new YAHOO.util.ColorAnim(element, {
  3. backgroundColor: {
  4. to: '#dcdcdc'
  5. }
  6. });
  7. myAnim.animate();
  8.  
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:

  1. var myAnim = new YAHOO.util.Motion('test', {
  2. points: {
  3. to: [400, 400]
  4. }
  5. });
  6. myAnim.animate();
  7.  
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:

  1. var attributes = {
  2. points: {
  3. to: [400, 400],
  4. control: [[800, 300], [-200, 400]]
  5. }
  6. };
  7. var myAnim = new YAHOO.util.Motion('test', attributes);
  8. myAnim.animate();
  9.  
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:

  1. var element = document.getElementById('test');
  2. var myAnim = new YAHOO.util.Scroll(element, {
  3. scroll: {
  4. to: [ 500, test.scrollTop ]
  5. }
  6. });
  7. myAnim.animate();
  8.  
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

About this Section: YUI generally works well with mobile browsers that are based on A-Grade browser foundations. For example, Nokia's N-series phones, including the N95, use a browser based on Webkit — the same foundation shared by Apple's Safari browser, which is found on the iPhone. The fundamental challenges in developing for this emerging class of full, A-Grade-derived browsers on handheld devices are:

  • Screen size: You have a much smaller canvas;
  • Input devices: Mobile devices generally do not have mouse input, and therefore are missing some or all mouse events (like mouseover);
  • Processor power: Mobile devices have slower processors that can more easily be saturated by JavaScript and DOM interactions — and processor usage affects things like battery life in ways that don't have analogues in desktop browsers;
  • Latency: Most mobile devices have a much higher latency on the network than do terrestrially networked PCs; this can make pages with many script, css or other types of external files load much more slowly.

There are other considerations, many of them device/browser specific (for example, current versions of the iPhone's Safari browser do not support Flash). The goal of these sections on YUI User's Guides is to provide you some preliminary insights about how specific components perform on this emerging class of mobile devices. Although we have not done exhaustive testing, and although these browsers are revving quickly and present a moving target, our goal is to provide some early, provisional advice to help you get started as you contemplate how your YUI-based application will render in the mobile world.

More Information:

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 YUILibrary.com forums.

Also be sure to check out 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 YUILibrary.com site. Before filing new feature requests or bug reports, please review our reporting guidelines.

Animation Utility Cheat Sheet:

Cheat Sheet for the Animation Utility.

Download full set of cheat sheets.

More Reading about the YUI Animation Utility:

YUI Animation on del.icio.us:

Copyright © 2013 Yahoo! Inc. All rights reserved.

Privacy Policy - Copyright Policy - Job Openings