WinJS.UI.executeAnimation function

Asynchronously executes a collection of Cascading Style Sheets (CSS) animations on a collection of elements. This is the underlying animation mechanism used by the Animations Library. Apps are encouraged to use the Animations Library to conform with the standard look and feel of the rest of the system, rather than calling this function directly.

Syntax

WinJS.UI.executeAnimation(element, animation).done( /* Your success and error handlers */ );

Parameters

• element
  Type: Object

  Element or elements to be animated. This parameter can be expressed in several ways:

  • As the special value "undefined", which means that the animation has no target
  • As a single object
  • As a JavaScript array (possibly empty), in which each element of the array can be a single element or a JavaScript array of elements.
  • As a NodeList (for example, the result of querySelectorAll)
  • As an HTMLCollection

• animation
  Type: Object

  The animation description or an array of animation descriptions to apply to element. An animation description is a JavaScript object with specific properties, listed below. There are two types of animation descriptions: one for keyframe-based animations and one for explicit animations. These types are distinguished by whether the keyframe property has a defined value.

  The following properties are required for both types of animation descriptions:

  • property (string): The CSS property to animate, such as "opacity".
  • delay (number): The amount of time, in milliseconds, before the animation begins.
  • duration (number): The amount of time, in milliseconds, the animation takes to execute once it has begun.
  • timing (string): The CSS timing function that controls the progress of the animation.

  If an animation has a keyframe property with a defined, non-null value, then the animation is a keyframe-based animation. A keyframe-based animation description requires the following property in addition to those mentioned above:

  • keyframe (string): The name of an animation keyframe defined in the page's CSS style sheet. The CSS property controlled by the animation keyframe must be the same CSS property described by the property property.

  If an animation does not have a keyframe property, or if the value of the property is null or undefined, then the animation is an explicit animation. An explicit animation description requires the following properties in addition to the common properties mentioned above:

  • from: The initial value of the CSS property.
  • to: The final value for the CSS property.

  The values given in the from and to properties must be valid for the CSS property specified by the property property. For example, if the CSS property is "opacity", then the from and to properties must be numbers between 0 and 1 (inclusive).

Return value

Type: Promise**

Returns a Promise object that completes when the CSS animation is complete.

Remarks

The executeAnimation function is provided in the case that your app performs an animation that isn't available in the Animations Library, but you would like to use the same underlying animation engine to perform the animation. (Apps are strongly encouraged to use Animations Library animations where available.) Using the same animation engine as the Animations Library permits your custom animations to coexist with the Animation Library animations. It provides the convenience of respecting the isAnimationEnabled state and returning a Promise object that can be used to cancel the animation or to register for its completion.

The value of any of the animation description properties provided through the animation parameter can be given in the form of a function. This function is called with two parameters.

• The zero-based index of the element to which the CSS animation will be applied
• The element itself

The function's return value is used as the value of that property in the CSS animation as applied to that element.

Examples

The following example shows a call to this function.

return WinJS.UI.executeAnimation(
    element,
    {
        property: "opacity",
        delay: 0,
        duration: 83,
        timing: "linear",
        from: 1,
        to: 0
    });

The function's animation parameter can contain multiple animation objects as an array. This allows you to trigger different animations against different properties simultaneously or in sequence. The following code animates both opacity and transform.

return WinJS.UI.executeAnimation(
    element,
    [{
        property: "opacity",
        delay: 83,
        duration: 83,
        timing: "linear",
        from: 0,
        to: 1
    },
    {
        property: "transform",
        delay: 0,
        duration: 367,
        timing: "cubic-bezier(0.1, 0.9, 0.2, 1)",
        from: translateCallback(offsetArray),
        to: "translate(0px, 0px)"
    }]);

Requirements

Minimum WinJS version	WinJS 3.0
Namespace	WinJS.UI

See also

executeTransition

HTML ListView essentials sample