Skip to content
Get packs

Guide · Open source

How to use Velocity: install and animate elements in JavaScript

Updated · written with AI from the project's own documentation and checked against our catalogue data

Velocity is an open-source JavaScript library that animates elements on a web page, such as moving, fading or resizing them. It works as a standalone alternative to jQuery's $.animate(), and the README says it can be used with or without jQuery. This guide shows how to add it to a project, how the chained .velocity() call works, and what to check before you rely on it.

Velocityjulianshapiro/velocity · ★ 17.2k · MIT

Quick start

  1. 1Install the beta. Run npm install velocity-animate@beta in your project folder.
  2. 2Load the library. Import or include the Velocity file in your page, or add a CDN script tag from the README.
  3. 3Order your scripts. If you use the chained call with jQuery or Zepto, load those libraries before Velocity.
  4. 4Animate an element. Call Velocity on an element and pass the properties you want to change, such as position, opacity or size.
  5. 5Check the wiki. Look up current method details in the GitHub wiki rather than the velocityjs.org V1 docs.

Install Velocity with npm

The README's package-manager install uses the beta build from npm. The repository lists no separate prerequisites.

Run the command in your project folder. The package name is velocity-animate, and the @beta tag selects the V2 beta.

npm install velocity-animate@beta

Load Velocity from a CDN instead

If you do not use a package manager, the README gives two CDN options for the main file and the UI pack. jsDelivr can supply the latest release automatically, while cdnjs needs a specific version number in the URL.

Use the velocity.ui.min.js file only if you want the UI pack in addition to the core library.

  • Core file on jsDelivr: velocity-animate@2.0/velocity.min.js
  • Core file on cdnjs: velocity/2.0.6/velocity.min.js
  • UI pack on jsDelivr: velocity-animate@2.0/velocity.ui.min.js
<script src="//cdn.jsdelivr.net/npm/velocity-animate@2.0/velocity.min.js"></script>

Use the chained .velocity() call with jQuery or Zepto

If you call the chained .velocity(...) function in libraries such as jQuery or Zepto, load Velocity after them. This order matters because Velocity attaches itself to those libraries.

If you add Velocity to a page after those libraries have loaded, the README points to the Velocity.patch() method, described in the project wiki.

  • Load jQuery or Zepto first, then Velocity.
  • Use Velocity.patch() for libraries loaded later.

Find current documentation in the wiki

The README warns that the velocityjs.org documentation refers to V1, not the V2 beta. For the latest documentation, use the project wiki on GitHub.

Check the wiki before copying any API example from older tutorials, since method details may differ between versions.

  • Current docs: github.com/julianshapiro/velocity/wiki
  • Older docs: VelocityJS.org (V1)

Know when Velocity fits and when it does not

The README says CSS transitions are meant for simple interface flourishes, such as hover or fade effects. Velocity is aimed at more involved motion work.

The README also labels the project beta, and the last push to the repository was in October 2020. Weigh that before choosing it for a new production project.

  • Good fit: maintaining a site that already uses Velocity, or needing pause/resume and custom easings.
  • Poor fit: simple hover or fade effects, or teams that need actively maintained software.

What people use it for

  • Moving and resizing page elements with more control than jQuery's $.animate() offers.
  • Pausing and resuming animations, a feature the README lists from version 1.4.
  • Defining custom easing curves for interface motion.
  • Maintaining an existing website that already uses Velocity.

Frequently asked questions

How do I install Velocity?

Run npm install velocity-animate@beta in your project folder. You can also load it from a CDN with a script tag, using jsDelivr or cdnjs as shown in the README.

Does Velocity require jQuery?

No. The README says Velocity can be used with or without jQuery. If you use the chained .velocity() call with jQuery or Zepto, load Velocity after them.

Is Velocity free to use?

Velocity is released under the MIT License, as stated in the README. The license file is named LICENSE.md in the repository.

What is the difference between Velocity and jQuery's $.animate()?

The README describes jQuery's $.animate() as slow and poorly equipped for motion design. It presents Velocity as a fast, feature-rich standalone alternative.

Why does the Velocity documentation not match my code?

The velocityjs.org documentation refers to V1, while the npm beta is V2. The README recommends the GitHub wiki for the latest documentation.

What are good alternatives to Velocity?

The project's comparable projects listed for this directory are GSAP, Anime.js, Motion One and jQuery UI. For simple hover or fade effects, the README suggests CSS transitions instead.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Velocity suits front-end developers who want more control over JavaScript animation than jQuery's $.animate() offers, and teams maintaining existing sites that already use it. Pick something else if you only need simple hover or fade effects, which CSS transitions handle, or if you need actively maintained software, since the project is labelled beta and its last push was in October 2020.

Install options & downloads