{"id":15261,"library":"velocity-react","title":"React Velocity Animation Components","description":"velocity-react provides a set of React components designed to integrate the Velocity.js DOM animation library into React applications. Key components include `VelocityComponent` for animating a single child, and `VelocityTransitionGroup` for managing animations during component mounting, unmounting, and updates. The current stable version is v1.4.3, released in May 2019. This package acts as a bridge, allowing React developers to leverage Velocity.js's performance and declarative API within their component-based UIs, contrasting with CSS-based animations or other JavaScript animation libraries by providing a more direct imperative control over DOM animations through React props. Its release cadence has been very slow, with no updates since 2019, strongly suggesting it is no longer actively maintained.","status":"abandoned","version":"1.4.3","language":"javascript","source_language":"en","source_url":"https://github.com/twitter-fabric/velocity-react","tags":["javascript","velocity","react","animation"],"install":[{"cmd":"npm install velocity-react","lang":"bash","label":"npm"},{"cmd":"yarn add velocity-react","lang":"bash","label":"yarn"},{"cmd":"pnpm add velocity-react","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for React applications. Requires ^15.3.0 || ^16.0.0.","package":"react","optional":false},{"reason":"Peer dependency for React applications, particularly for rendering. Requires ^15.3.0 || ^16.0.0.","package":"react-dom","optional":false},{"reason":"Core animation engine. Must be explicitly imported/required at an app entry point for Velocity functionality and UI pack.","package":"velocity-animate","optional":false},{"reason":"Internal utility functions, used individually to minimize bundle size.","package":"lodash","optional":false}],"imports":[{"note":"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.","wrong":"const VelocityComponent = require('velocity-react').VelocityComponent;","symbol":"VelocityComponent","correct":"import { VelocityComponent } from 'velocity-react';"},{"note":"This is a named export, not a default export. Ensure you destructure it correctly when importing.","wrong":"import VelocityTransitionGroup from 'velocity-react';","symbol":"VelocityTransitionGroup","correct":"import { VelocityTransitionGroup } from 'velocity-react';"},{"note":"Utility functions are exported alongside components from the main package entry point.","wrong":"import * as velocityHelpers from 'velocity-react/velocityHelpers';","symbol":"velocityHelpers","correct":"import { velocityHelpers } from 'velocity-react';"}],"quickstart":{"code":"import React, { useState } from 'react';\nimport ReactDOM from 'react-dom';\nimport { VelocityComponent } from 'velocity-react';\n\n// IMPORTANT: Ensure Velocity.js and its UI pack are loaded globally or via your bundler\n// In a typical application entry point (e.g., index.js, App.js), you would add:\n// require('velocity-animate');\n// require('velocity-animate/velocity.ui'); // If you plan to use UI pack effects\n\nfunction AnimatedBox() {\n  const [isVisible, setIsVisible] = useState(true);\n\n  return (\n    <div style={{ padding: '20px' }}>\n      <button onClick={() => setIsVisible(!isVisible)}>\n        Toggle Animated Box\n      </button>\n      <VelocityComponent\n        animation={isVisible ? { opacity: 1, translateX: 0 } : { opacity: 0, translateX: 50 }}\n        duration={500}\n        easing=\"ease-in-out\"\n        runOnMount={true} // Animates on initial mount\n      >\n        <div\n          style={{\n            width: '120px',\n            height: '120px',\n            backgroundColor: '#61dafb',\n            marginTop: '20px',\n            borderRadius: '10px',\n            display: isVisible ? 'flex' : 'none', // Use display: 'none' to remove from flow when hidden\n            alignItems: 'center',\n            justifyContent: 'center',\n            color: 'white',\n            fontSize: '18px',\n            fontWeight: 'bold'\n          }}\n        >\n          Velocity Box\n        </div>\n      </VelocityComponent>\n    </div>\n  );\n}\n\n// Standard ReactDOM rendering setup for a client-side application\nconst rootElement = document.getElementById('root');\nif (!rootElement) {\n  const newRoot = document.createElement('div');\n  newRoot.id = 'root';\n  document.body.appendChild(newRoot);\n}\n// For React 18+, use createRoot. For compatibility, this example uses ReactDOM.render.\nReactDOM.render(<AnimatedBox />, document.getElementById('root'));","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.4.3"},{"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.","message":"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.","severity":"breaking","affected_versions":">=1.4.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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');`.","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.","error":"ReferenceError: Velocity is not defined"},{"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.","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.","error":"Warning: componentWillUpdate has been renamed, and is not recommended for use. See https://react.dev/warnings/deprecate-legacy-lifecycles for details."},{"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');`.","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.","error":"Uncaught TypeError: Cannot read properties of undefined (reading 'ui') (or similar for velocity.ui)"}],"ecosystem":"npm"}