Option Progress

- NOTE: This documentation is for Velocity v2.

Option: Progress

Pass the progress option a callback function to be repeatedly triggered throughout the duration of an animation. The callback function is passed data on the status of the call (see VelocityProgress in index.d.ts). This data can be leveraged for custom tweening and more. This is always called on the first element to be animated in the animation.

The callback is passed the element array as both its context and its first argument. To access these elements individually, you must iterate over the array. This array also has .velocity(...) available on it for addressing directly. Further, it's passed: complete, remaining, tweenValue, and activeCall:

complete: The call's completion percentage (as a decimal value, for example 0.5 means 50% through). remaining: How much time remains until the call completes (in ms). tweenValue: The current value of the dummy tween animation property, which can optionally be passed into a Velocity call. The utility of passing in the tween animation property is that it allows you to then capture the exact value of its tween progression via the progress callback. This dummy property, like all other Velocity animation properties, is subject to the call's easing behavior. Leveraging this tween property allows you to turn Velocity into a custom tweening engine so that you animate the change of arbitrary DOM properties. activeCall: An AnimationCall (see index.d.ts in the source for full details). The most useful members of this object are .element for the current element, and .timeStart for when it began (for accuracy this is relative to the page load and not a timestamp).

element.velocity({
    opacity: 0,
    tween: 1000 // Optional
}, {
    progress: function(elements, percentComplete, remaining, tweenValue, activeCall) {
        console.log("Current element:", activeCall.element);
        console.log((percentComplete * 100) + "%");
        console.log("Started at", new Date(Date.now() - activeCall.ellapsedTime));
        console.log(remaining + "ms remaining!");
        console.log("The current tween value is", tweenValue);
    }
});

Note that you can pass the dummy tween value along with other properties as well; tween doesn't have to stand alone. Further, note that you can forcefeed the tween property to start from an arbitrary offset. If you don't forcefeed a starting value, the tween will start from a value of "0".

The tween does not have to be a number, as it follows all the same rules for animating

$element.velocity({
    tween: [ 0, 1000 ]
}, {
    progress: function(elements, percentComplete, remaining, tweenValue, activeCall) {
        console.log("The current tween value is " + tweenValue)
    }
});

Changes from v1

• The timeStart argument is no longer passed - now it is not an actual Unix timestamp it is safer to not use it unless absolutely necessary. If you need that timestamp then use Date.now() - activeCall.ellapsedTime.