Advanced Promises

- NOTE: This documentation is for Velocity v2.

Feature: Promises

If you're new to promises, read this article.

A Velocity call automatically returns a promise object when promise support is detected in the browser (see Browser Support below for further details). This is an overlap with the array of elements and .velocity() chain - they all get returned in one object.

/* Using Velocity's utility function... */
elements.velocity(element, { opacity: 0.5 })
    /* Callback to fire once the animation is complete. */
    .then(function(elements) { console.log("Resolved."); })
    /* Callback to fire if an error occurs. */
    .catch(function(error) { console.log("Rejected."); });

The returned promise is resolved when the call's animation completes, regardless of whether it completed on its own or prematurely due to the user calling the "stop" command. The resolve function is passed the element array as both its context and its first argument. To access these elements individually, you must iterate over the array.

Conversely, the promise is rejected when an invalid first argument is passed into a Velocity call (e.g. an empty properties object or a string command that does not exist).