Velocity.js Animation Library

Common errors

• ReferenceError: Velocity is not defined

  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).
  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.

• TypeError: (element).velocity is not a function

  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.
  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.

Warnings

• breaking 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).
  Fix: Refer to the official V2_CHANGES.md documentation for a detailed migration guide, as many options and behaviors were altered.
• breaking 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.
  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.
• gotcha 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.
  Fix: Adopt `.then()` or `async/await` syntax for managing animation sequences and completion, instead of relying solely on `complete` callbacks.
• gotcha 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'.
  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.
• gotcha 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.
  Fix: For optimal performance and bundle size, if using Velocity without jQuery's animation module, custom-build jQuery to exclude its `effects` module.

Install

• npm install velocity-animate npm
• yarn add velocity-animate yarn
• pnpm add velocity-animate pnpm

Imports

• Velocity
  wrong:

  const Velocity = require('velocity-animate');

  correct:

  import Velocity from 'velocity-animate';

  This is the primary ES Module import for modern JavaScript environments.
• Velocity
  wrong:

  import Velocity from 'velocity-animate';

  correct:

  const Velocity = require('velocity-animate');

  This is the CommonJS `require` syntax, commonly used in Node.js or older build setups. Do not mix with ES Modules.
• Velocity

  // Global in browser after <script src="velocity.min.js"></script>

  When loaded directly via a script tag in the browser, Velocity is exposed as a global `Velocity` object.
• Properties, Easing, ElementCallback

  import type { Properties, Easing, ElementCallback } from 'velocity-animate';

  Velocity.js provides TypeScript definitions for its core types, enabling stronger type checking in TypeScript projects.

Quickstart

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.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Velocity.js Quickstart</title>
    <style>
        #myElement {
            width: 100px;
            height: 100px;
            background-color: steelblue;
            position: absolute;
            top: 50px;
            left: 50px;
            border-radius: 5px;
            display: flex;
            align-items: center;
            justify-content: center;
            color: white;
            font-family: sans-serif;
            font-size: 1.2em;
        }
    </style>
</head>
<body>
    <div id="myElement">Animate Me</div>

    <script type="module">
        import Velocity from 'velocity-animate';

        const element = document.getElementById('myElement');

        Velocity(element, {
            translateX: '200px',
            rotateZ: '360deg',
            backgroundColor: '#ef5350'
        }, {
            duration: 1500,
            easing: 'ease-in-out',
            loop: 2,
            delay: 500,
            complete: () => {
                console.log('Animation complete!');
                // Chain another animation using Promises (V2 feature)
                Velocity(element, {
                    scale: 0.8,
                    opacity: 0.5
                }, {
                    duration: 800,
                    easing: [250, 15] // Custom bezier easing
                }).then(() => {
                    console.log('Second animation complete!');
                    element.textContent = 'Done!';
                });
            }
        });

        // Example of animating another element concurrently
        const anotherElement = document.createElement('div');
        anotherElement.id = 'anotherElement';
        anotherElement.style.cssText = `
            width: 80px; height: 80px; background-color: goldenrod;
            position: absolute; top: 200px; left: 50px; border-radius: 50%;
            display: flex; align-items: center; justify-content: center;
            color: white; font-size: 0.9em;
        `;
        anotherElement.textContent = 'Hello';
        document.body.appendChild(anotherElement);

        Velocity(anotherElement, {
            left: '300px',
            top: '250px',
            backgroundColor: 'purple'
        }, {
            duration: 1000,
            delay: 1000,
            begin: () => console.log('Starting second element animation')
        });
    </script>
</body>
</html>