{"id":12350,"library":"velocity-animate","title":"Velocity.js Animation Library","description":"Velocity.js is a high-performance JavaScript animation library that provides a feature-rich and fast alternative to traditional methods like jQuery's `$.animate()` or basic CSS transitions. It enables complex UI motion design by optimizing DOM interactions to minimize layout thrashing and leveraging efficient JavaScript animation techniques. Key features include support for color animations, CSS transforms, loops, easings, SVG properties, and scrolling. Velocity.js offers an API that closely mirrors jQuery's `$.animate()`, allowing for seamless integration with or independent use from jQuery. The library is currently stable at version 2.0.6, released in September 2023, demonstrating ongoing maintenance and development. This version integrated the former `UI-Pack` animations directly into its core and introduced a Promise-based API for modern asynchronous control flow. It aims to deliver significantly smoother animations, especially on mobile devices, by focusing on performance at its core.","status":"active","version":"1.5.2","language":"javascript","source_language":"en","source_url":"https://github.com/julianshapiro/velocity","tags":["javascript","velocity","animation","jquery","animate","ui","velocity.js","velocityjs"],"install":[{"cmd":"npm install velocity-animate","lang":"bash","label":"npm"},{"cmd":"yarn add velocity-animate","lang":"bash","label":"yarn"},{"cmd":"pnpm add velocity-animate","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This is the primary ES Module import for modern JavaScript environments.","wrong":"const Velocity = require('velocity-animate');","symbol":"Velocity","correct":"import Velocity from 'velocity-animate';"},{"note":"This is the CommonJS `require` syntax, commonly used in Node.js or older build setups. Do not mix with ES Modules.","wrong":"import Velocity from 'velocity-animate';","symbol":"Velocity","correct":"const Velocity = require('velocity-animate');"},{"note":"When loaded directly via a script tag in the browser, Velocity is exposed as a global `Velocity` object.","symbol":"Velocity","correct":"// Global in browser after "},{"note":"Velocity.js provides TypeScript definitions for its core types, enabling stronger type checking in TypeScript projects.","symbol":"Properties, Easing, ElementCallback","correct":"import type { Properties, Easing, ElementCallback } from 'velocity-animate';"}],"quickstart":{"code":"\n\n\n \n \n Velocity.js Quickstart\n \n\n\n Animate Me
\n\n \n\n","lang":"typescript","description":"This quickstart demonstrates animating a DOM element using Velocity.js ES module import. It shows basic property animation, chaining with Promises, custom easing, looping, and parallel animations."},"warnings":[{"fix":"Refer to the official V2_CHANGES.md documentation for a detailed migration guide, as many options and behaviors were altered.","message":"Velocity.js v2 introduced significant API changes compared to v1, including a re-written Sequences module and modifications to how properties like `display` and `visibility` are handled (now properties, not options).","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Remove separate imports or script tags for `velocity.ui.js`. Animations previously provided by the UI-Pack are now accessible directly through the main `Velocity` object.","message":"In Velocity.js v2.0.6 and later, the `velocity.ui.js` module is no longer distributed separately; its core animations have been integrated directly into the main `velocity-animate` package.","severity":"breaking","affected_versions":">=2.0.6"},{"fix":"Adopt `.then()` or `async/await` syntax for managing animation sequences and completion, instead of relying solely on `complete` callbacks.","message":"Velocity.js v2 primarily uses a Promise-based API for chaining animations and handling completion, a departure from the callback-centric approach of v1. While callbacks still exist, Promises are the idiomatic way to handle asynchronous flow.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Ensure consistent module usage throughout your project. For Node.js, either configure your `package.json` with `\"type\": \"module\"` for ESM, or stick to CommonJS `require()` and ensure packages are correctly transpiled or built for dual module support.","message":"Mixing ES Modules (`import`) and CommonJS (`require`) in Node.js environments can lead to errors like 'Cannot use import statement outside a module' or 'require is not defined'.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For optimal performance and bundle size, if using Velocity without jQuery's animation module, custom-build jQuery to exclude its `effects` module.","message":"While Velocity.js can seamlessly integrate with jQuery, if you replace jQuery's `$.animate()` with `$.velocity()`, you should consider building a custom jQuery version without its animation module to reduce file size, as Velocity.js provides its own animation stack.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"For ES Modules, use `import Velocity from 'velocity-animate';`. For CommonJS, use `const Velocity = require('velocity-animate');`. If using a script tag, ensure `velocity.js` is loaded before your animation code, and `Velocity` will be available globally.","cause":"The `Velocity` object was not correctly imported, the script was not loaded, or it was loaded in a way that doesn't expose it globally in the current scope (e.g., using a module bundler without proper configuration).","error":"ReferenceError: Velocity is not defined"},{"fix":"If you intend to use jQuery, ensure jQuery is loaded *before* Velocity.js. If not using jQuery, animate raw DOM elements directly using `Velocity(element, properties, options);` rather than attempting to call `.velocity()` as a method on the element itself or a jQuery object.","cause":"This error typically occurs when attempting to use Velocity.js with a jQuery-like chaining syntax (`$(element).velocity(...)`) but jQuery is either not loaded, or Velocity.js was not correctly integrated with jQuery, or you're trying to use chaining on a raw DOM element without the `Velocity(element, ...)` utility function.","error":"TypeError: (element).velocity is not a function"}],"ecosystem":"npm"}