jQuery is great, but it’s slow when you’re doing animations on your website. Enter Velocity.js: bypassing jQuery and directly using JavaScript animations (which are fast), Velocity offers superfast animations by synchronizing the DOM and the tween stack and caching values to minimize DOM queries. Also, it uses hardware acceleration. This tutorial will show you how to use Velocity.js.

The Velocity.js animation engine works with and without jQuery (you can use them side by side). It offers blazing speed, featuring scrolling, color animation, loops, transforms, easings and SVG support. What’s more, it uses the exact same API as jQuery $.animate(), so you can plug it into your project right away with no additional work. All you need to do is replace all instances of $.animate() with $.velocity(). There is also a special UI pack that offers access to a number of pre-registered animation effects that have you animating your DOM in no time.

Since Velocity.js replaces that jQuery animation routines, you can save a few kilobytes of JavaScript that users must download by custom-building jQuery without its effects module (see jQuery on GitHub), which Velocity.js does not rely on. Obviously you can then no longer use jQuery’s animation module.

Setting up Velocity.js

Adding Velocity.js to your website is as simple as referencing it from a content delivery network (CDN). Either that, or you can download it from the Velocity.js website, copy the files to your working directory and link them from there. Let’s reference both jQuery and Velocity.js by adding the following just before the closing </body> element of a page:

  <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.12.4/jquery.min.js"></script>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/velocity/1.2.3/velocity.min.js"></script>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/velocity/1.2.3/velocity.ui.min.js"></script>

(Adding the scripts before the </body> element rather than inside the <head> element will make sure that the page loads before the scripts do, resulting in a better user experience.)

Your first animation with Velocity.js

Animating with Velocity.js is, just like with jQuery, easy enough. Assuming there is an element with ID myelement on your page, you can fade it in over a period of 1.5 seconds by writing this:

$("#myelement").velocity("fadeIn", { duration: 1500 });

Of course, we used jQuery here to get a hold of the element to animate, but you don’t have to. Velocity.js works just as well without jQuery (but bear in mind that this code only works when jQuery is not present, otherwise the Velocity function is not defined):

Velocity(document.getElementById("myelement"), "fadeIn", { duration: 1500 });

We’ll be using jQuery in the rest of this tutorial for brevity.

Velocity.js syntax

The common syntax used to do an animation with Velocity.js is this:

  { property1: value,
    property2: value },
  { option1: value,
    option2: value }

or, without jQuery:

  { property1: value,
    property2: value },
  { option1: value,
    option2: value }

The call to Velocity.js has two arguments. The first argument is a group of properties that Velocity.js must animate, and the second argument is a group of options that influence how the animation should be done. Velocity.js comes with default values for all options, so you only have to specify option overrides. For example, to animate the opacity of an element, you would do:

  { opacity: 0.5 },
  { duration: 1000 }

This is all you need. The next few paragraphs provide alternative syntax and shortcuts!

Velocity.js also pass you to pass all arguments as a single object, if you prefer that:

    properties: { opacity: 0.5 },
    options: { duration: 1000 }

or shorter:

    p: { opacity: 0.5 },
    o: { duration: 1000 }

There is also a shortcut for often-used options. You can pass in the effect duration, easing and completion function directly, without using an object (and this only applies to these properties). For instance, for a duration only:

$element.velocity( { opacity: 0.5}, 1000);

Here’s one with easing and a completion callback as well:

$element.velocity( { opacity: 0.5}, 1000, "swing", function() { console.log("effect done."); } );

Velocity.js animation chaining

If you want to show multiple animations on an element, one after the other, you can chain them:

  .velocity( { opacity: 0.5 }, { duration: 1000 } )
  .velocity( { opacity: 1.0 }, { duration: 1000 } );

In this example, the element opacity will fade out to 50%, then back in again to 100%, and the second animation will not start before the first one is finished.

Looping animations with Velocity.js

If you want an animation to execute more than once, you can loop it. When you add a loop property, the animation will execute in and out for every count in the loop. For instance, this will have the element fade out and fade back in twice:

$element.velocity( { opacity: 0.1 }, { duration: 500, loop: 2 } );

You can also set loop to true, which will cause infinite looping. If you want a pause between cycles, you can add the option delay: 100 (to wait 100ms between loops). When used without a loop, delay will cause the animation to pause for the specified time before it starts.

Velocity.js Commands

Although you can create every animation by specifying exactly which CSS properties must change, you can also benefit from Velocity.js built-in commands. These commands have names that serve as a mnemonic, and implement all the CSS properties that are needed to perform the animation.

For example, the fadeIn command fades an element in (warning: ‘fadein’ is not the same as ‘fadeIn’):

$element.velocity( { "fadeIn", { duration: 1000 } );

It will comes as no surprise that there is also a fadeOut command. Similarly, there are slideIn and slideOut commands which animate an element’s height to or from zero:

$element.velocity( { "slideOut", { duration: 500 } );

There are other commands still. The stop command stops all animation on an element, while the finish command jumps straight to the end of a running animation. The difference between the two is that stop leaves the element’s properties what they were when the animation was aborted, while finish sets them to the values they would have had, had the animation completed fully.

Velocity.js Pre-registered Effects

When we set up Velocity.js at the beginning of this article, we were careful to include the Velocity.js UI pack as well. This UI pack adds a list of interesting pre-registered effects to Velocity.js, so that you don’t have to build them yourself. An example of this are the range of callout effects that the UI pack offers, which are helpful when prompting the user to input data. We could add a bounce to an input field using the following code:

$field.velocity( { "callout.bounce", { duration: 1000 } );

Other callout variations are shake, flash, pulse, swing and tada. Apart from the callouts, there’s a crazy number of transition effects like swoopIn, perspectiveUpIn and expandOut. It’s best to try them all out to get a feel for what’s available!

Using Velocity.js with AngularJS

There’s a nice AngularJS module available that allows you to use Velocity.js with AngularJS. To use it, make sure you’ve included ngAnimate and the velocity module, and load both modules into your AngularJS app:

angular.module('myApp', ['velocity.ui', 'ngAnimate']);

After that, you can set certain classes on the elements you want to animate using ng-repeat, ng-if, ng-show and ng-hide. For example:

<div ng-repeat="item in items" class="velocity-transition-slideDownIn velocity-duration-400">

You can set durations using the velocity-duration-xxx class, where xxx is the animation duration in milliseconds.


To use Velocity.js, do:

  • Link Velocity.js from a CDN just before </body> (you don’t need jQuery, but you can still use it if you want)
  • Animate using $element.velocity( { properties }, { options })
  • Use pre-registered animations using $element.velocity( "animation", { options } )

Happy animating!