Basic Arguments

- NOTE: This documentation is for Velocity v2.

Basics: Arguments

Overview

Velocity can be called in two distinct ways, either as a function call, or as a chained call. In both cases the arguments are identical except for this way of calling Velocity itself.

If simply included along with jQuery or Zepto then Velocity will add itself to those for chaining, it will also add itself to global DOM selection methods such as querySelectorAll() and getElementById().

IMPORTANT

The return value from both is identical, however there is one minor but very important difference in using it:

• If passing the result from another Velocity call, then calling Velocity(result, ...) as a function will target the elements as a completely new call, for commands like "stop" this means that the active animations on them will be stopped.

• If instead they are used for chaining as result.velocity(...) then it will instead target the animations added in the result so that "stop" will only stop those specific animations if they are running, and nothing else running on those elements.

Velocity global

In this form the call is made to Velocity(...) itself, and the first argument is an element or list of elements that are to be animated, followed by the properties or other arguments.

var elements = document.querySelector("div");

Velocity(elements, {"color": "red"});

Velocity chaining

In this preferred form the element or list is selected, and then the .velocity() call is chained with the first argument jumping directly to the properties.

document.querySelector("div").velocity({"color": "red"});

Properties

Velocity takes a map of CSS properties and values as its first argument. An options object can optionally be passed in as a second argument:

element.velocity({
    width: "500px"
}, {
    duration: 400,
    easing: "swing",
    queue: "",
    begin: undefined,
    progress: undefined,
    complete: undefined,
    loop: false,
    delay: false
});

Option defaults can be globally overriden by modifying Velocity.defaults.

Single Object

Velocity also supports a single-argument syntax (which allows for more expressive CoffeeScript code). Simply pass in a single object with properties (or p) and options (or o) members:

element.velocity({
    properties: { opacity: 1 },
    options: { duration: 500 }
});

Or:

element.velocity({
    p: { opacity: 1 },
    o: { duration: 500 }
});

Comma-Separated

Instead of passing in an options object, Velocity also accepts jQuery style comma-separated syntax - but only for the duration, easing, and complete properties: element.velocity(propertyMap [, duration] [, easing] [, complete]).

These must be placed in this order, but may skip unused options:

$element.velocity({ top: 50 }, 1000);
$element.velocity({ top: 50 }, 1000, "swing");
$element.velocity({ top: 50 }, "swing");
$element.velocity({ top: 50 }, 1000, function() { alert("Hi"); });