Velocity auto-prefixes properties (e.g. transform becomes webkit-transform on WebKit browsers); do not prefix properties yourself. Velocity animates one numeric value per property. Hence, you can pass in: { padding: 1 } or { paddingLeft: 1, paddingRight: 1 }. But you cannot pass in { padding: "1 1 1 1" } because you're providing multiple numeric values.
Velocity supports the px, em, rem, %, deg, and vw/vh units. If you do not provide a unit, an appropriate one is automatically assigned — usually px, but deg in the case of rotateZ for example. Velocity supports four value operators: +, -, *, and /. You may suffix an equals sign onto any one of them to perform relative math operations.
Example code:
// Properties animation
$element.velocity({
marginLeft: 20,
marginRight: 20,
opacity: 0.5
}).velocity('reverse', {
delay: 1000,
complete: function() {
$(this).removeAttr('style');
}
});When multiple Velocity calls are stacked onto an element (or a series of elements), they automatically queue onto one another — with each one firing once its prior animation has completed. Current example demonstrates animation of left margin; then, when finished, animate the right margin property, then animate opacity property. To animate an element back to the values prior to its last Velocity call, pass in reverse as Velocity's first argument.
Example code:
// Chained animation
$element.velocity({
marginLeft: 20
}).velocity({
marginRight: 20
}).velocity({
opacity: 0.5
}).velocity('reverse', {
delay: 1000,
complete: function() {
$(this).removeAttr('style');
}
});Stagger
There are three options that work only with UI pack effects, but not with traditional Velocity calls: stagger, drag and backwards. They are passed into a UI pack call as standard Velocity call options.
Specify the stagger option in ms to successively delay the animation of each element in a set by the targeted amount. You can also pass in a value function to define your own stagger falloffs.
Example code:
// Stagger option
$element.velocity('transition.slideUpIn', {
stagger: 500
});Drag
Set the drag option to true to successively increase the animation duration of each element in a set. The last element will animate with a duration equal to the sequence's original value, whereas the elements before the last will have their duration values gradually approach the original value. The end result is a cross-element easing effect.
Example code:
// Drag option
$element.velocity('transition.slideUpBigIn', {
drag: true
});Backwards
Set the backwards option to true to animate starting with the last element in a set. This option is ideal for use with an effect that transitions elements out of view since the backwards option mirrors the behavior of elements transitioning into view (which, by default, animate in the forwards direction — from the first element to the last).
Example code:
// Drag option
$element.velocity('transition.slideDownOut', {
stagger: 400,
backwards: true
});Begin callback
Pass begin a function to be triggered prior to the start of the animation. As with complete, the begin callback is executed once per call, even if multiple elements are being animated. Further, if a call is looped, the begin callback only fires once — at the beginning of the first loop alternation.
The callback is passed the entire raw DOM (not jQuery) element array as both its context and its first argument. To access these elements individually, you must iterate over the array using jQuery's $.each() or JavaScript's native .forEach().
Example code:
// Begin callback
$element.velocity({
marginLeft: 20,
marginRight: 20,
opacity: 0.5
}, {
begin: function() {
alert('Begin callback example');
}
});Complete callback
Complete is the converse of the begin option. Pass the complete option a function to be triggered once the animation has finished. The function is executed once per call, even if multiple elements are being animated at once. Further, if a call is looped, the complete callback only fires once — at the end of the last loop alternation.
The callback is passed the entire raw DOM (not jQuery) element array as both its context and its first argument. To access these elements individually, you must iterate over the array using jQuery's $.each() or JavaScript's native .forEach().
Example code:
// Complete callback
$element.velocity({
marginLeft: 20,
marginRight: 20,
opacity: 0.5
}, {
complete: function() {
alert('Complete callback example');
}
});Progress callback
Pass the progress option a callback function to be repeatedly triggered througout the duration of the animation. The callback is passed the entire raw DOM (not jQuery) element array as both its context and its first argument. To access these elements individually, you must iterate over the array using jQuery's $.each() or JavaScript's native .forEach(). Further, it's passed percentComplete (decimal value), timeRemaining (in ms), and timeStart (Unix time).
Example code:
// Cache our jQuery objects
var $percentComplete = $("#percentComplete"),
$timeRemaining = $("#timeRemaining");
// Use the progress callback
$element.velocity({
marginLeft: 20,
marginRight: 20,
opacity: 0.5
}, {
progress: function(elements, percentComplete, timeRemaining, timeStart) {
$percentComplete.html(Math.round(percentComplete * 100) + "% complete.");
$timeRemaining.html(timeRemaining + "ms remaining.");
}
});