React Velocity Animation Components

Common errors

• ReferenceError: Velocity is not defined

  cause The core `velocity-animate` library, which `velocity-react` depends on, has not been properly loaded or made available in the global scope (or module scope) before `velocity-react` components attempt to use it.
  fix Add `require('velocity-animate');` at an entry point of your application, ensuring it executes before any `velocity-react` components are mounted. If using the UI pack, also add `require('velocity-animate/velocity.ui');`.

• Warning: componentWillUpdate has been renamed, and is not recommended for use. See https://react.dev/warnings/deprecate-legacy-lifecycles for details.

  cause React 16.3+ StrictMode flags deprecated lifecycle methods. `velocity-react`'s internal dependency on `react-transition-group` v2 utilizes these older APIs, leading to this warning.
  fix This is an upstream warning from `react-transition-group` v2 and is difficult to resolve directly within an unmaintained `velocity-react` project. You may choose to tolerate the warning or consider migrating to a modern animation library that fully supports newer React lifecycle methods.

• Uncaught TypeError: Cannot read properties of undefined (reading 'ui') (or similar for velocity.ui)

  cause This typically occurs when `velocity-animate/velocity.ui` is imported or required, but the main `velocity-animate` library is not found, or there are multiple instances of `velocity-animate` in `node_modules` leading to conflicting global `Velocity` objects.
  fix Ensure `velocity-animate` is explicitly listed in your `package.json` dependencies. Try running `npm dedupe` or `yarn install --force` to resolve potential duplicate `velocity-animate` installations. Verify that `require('velocity-animate');` is called *before* `require('velocity-animate/velocity.ui');`.

Warnings

• gotcha The `velocity-react` package has not been updated since May 2019, indicating it is unmaintained. It is highly likely to be incompatible with newer React versions (e.g., React 18+ and its concurrent features) and will not benefit from performance improvements or new APIs in modern React ecosystems.
  Fix: For new projects or applications requiring modern React compatibility, consider migrating to actively maintained animation libraries such as Framer Motion, React Spring, or directly utilizing CSS-in-JS solutions or CSS animations.
• breaking Starting with v1.4.0, the package migrated its internal dependency to `react-transition-group` v2. This introduced React 16.3+ StrictMode warnings due to upstream deprecated lifecycle methods (`componentWillUpdate`). While efforts were made to mitigate some, core `StrictMode` warnings might still persist, particularly if not using the latest `react-transition-group` v2 patches.
  Fix: These warnings primarily stem from an upstream dependency (`react-transition-group` v2). There is no direct fix within `velocity-react` itself due to its unmaintained status. Developers may choose to tolerate these warnings in `StrictMode` or explore alternative animation libraries.
• gotcha Explicitly importing or requiring `velocity-animate` and `velocity-animate/velocity.ui` at an application's entry point is critical for the animation library to be available globally (or in the correct scope). Failing to do so will result in `Velocity is not defined` runtime errors or UI pack effects not working.
  Fix: Ensure `require('velocity-animate');` and, if using UI effects, `require('velocity-animate/velocity.ui');` are placed at the top level of your main application file (e.g., `App.js` or `index.js`). Depending on your bundler configuration, you might also need to explicitly list `velocity-animate` in `package.json` dependencies to resolve `velocity-animate/velocity.ui` correctly.
• gotcha The `targetQuerySelector` prop allows `VelocityComponent` to animate descendant DOM nodes. However, this approach bypasses React's virtual DOM reconciliation and directly manipulates the DOM, which can lead to fragile behavior and potential conflicts with React's updates if not managed carefully.
  Fix: Prefer animating the direct child of `VelocityComponent` where possible. If `targetQuerySelector` is essential, use it with thorough testing and be mindful that React's reconciliation may not preserve the targeted nodes' state as expected during animations.

Install

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

Imports

• VelocityComponent
  wrong:

  const VelocityComponent = require('velocity-react').VelocityComponent;

  correct:

  import { VelocityComponent } from 'velocity-react';

  While the package uses CommonJS internally, modern build setups (e.g., Webpack, Vite) allow named ES module imports to function correctly. Avoid direct CommonJS `require` in new code unless strictly necessary.
• VelocityTransitionGroup
  wrong:

  import VelocityTransitionGroup from 'velocity-react';

  correct:

  import { VelocityTransitionGroup } from 'velocity-react';

  This is a named export, not a default export. Ensure you destructure it correctly when importing.
• velocityHelpers
  wrong:

  import * as velocityHelpers from 'velocity-react/velocityHelpers';

  correct:

  import { velocityHelpers } from 'velocity-react';

  Utility functions are exported alongside components from the main package entry point.

Quickstart

Demonstrates a basic `VelocityComponent` animating a box's opacity and horizontal position based on a state change, including explicit Velocity.js loading instructions for proper function.

import React, { useState } from 'react';
import ReactDOM from 'react-dom';
import { VelocityComponent } from 'velocity-react';

// IMPORTANT: Ensure Velocity.js and its UI pack are loaded globally or via your bundler
// In a typical application entry point (e.g., index.js, App.js), you would add:
// require('velocity-animate');
// require('velocity-animate/velocity.ui'); // If you plan to use UI pack effects

function AnimatedBox() {
  const [isVisible, setIsVisible] = useState(true);

  return (
    <div style={{ padding: '20px' }}>
      <button onClick={() => setIsVisible(!isVisible)}>
        Toggle Animated Box
      </button>
      <VelocityComponent
        animation={isVisible ? { opacity: 1, translateX: 0 } : { opacity: 0, translateX: 50 }}
        duration={500}
        easing="ease-in-out"
        runOnMount={true} // Animates on initial mount
      >
        <div
          style={{
            width: '120px',
            height: '120px',
            backgroundColor: '#61dafb',
            marginTop: '20px',
            borderRadius: '10px',
            display: isVisible ? 'flex' : 'none', // Use display: 'none' to remove from flow when hidden
            alignItems: 'center',
            justifyContent: 'center',
            color: 'white',
            fontSize: '18px',
            fontWeight: 'bold'
          }}
        >
          Velocity Box
        </div>
      </VelocityComponent>
    </div>
  );
}

// Standard ReactDOM rendering setup for a client-side application
const rootElement = document.getElementById('root');
if (!rootElement) {
  const newRoot = document.createElement('div');
  newRoot.id = 'root';
  document.body.appendChild(newRoot);
}
// For React 18+, use createRoot. For compatibility, this example uses ReactDOM.render.
ReactDOM.render(<AnimatedBox />, document.getElementById('root'));