WinJS.UI.executeTransition function

Article
01/26/2017

Asynchronously executes a collection of Cascading Style Sheets (CSS) transitions 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.executeTransition(element, transition).done( /* Your success and error handlers */ );

Parameters

element
Type: Object

Element or elements on which to perform the transition. This parameter can be expressed in several ways:
- As the special value "undefined", which means that the transition 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
transition
Type: Object

The transition description or an array of transition descriptions to apply to element. A transition description is a JavaScript object with these properties:
- property (string): The CSS property on which to perform a transition, such as "opacity".
- delay (number): The amount of time, in milliseconds, before the transition begins.
- duration (number): The amount of time, in milliseconds, the transition takes to execute once it has begun.
- timing (string): The CSS timing function that controls the progress of the transition.
- from (optional): The initial value of the CSS property. If this property is omitted, then the element's current CSS property value is used.
- to: The final value of 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 that completes when the transition is finished.

Remarks

The executeTransition function is provided in the case that your app performs a transition 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 transition or to register for its completion.

The value of any of the transition description properties provided through the transition 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 transition will be applied
The element itself

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

Examples

The following example shows a call to this function.

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

The function's transition parameter can contain multiple transition objects as an array. This allows you to trigger different transitions against different properties simultaneously or in sequence. The following code transitions both the opacity and mstransform properties.

return WinJS.UI.executeTransition(
    element,
    [{
        property: transform,
        delay: 0,
        duration: 240,
        timing : "cubic-bezier(0.1, 0.9, 0.2, 1)",
        to: "scale(1.05 , 1.05)"
    },
    {
        property: "opacity",
        delay: 0,
        duration: 240,
        timing: "cubic-bezier(0.1, 0.9, 0.2, 1)",
        to: 0.65
    }]);

Requirements

Minimum WinJS version	WinJS 3.0
Namespace	WinJS.UI