React-Move Animation Library

Common errors

• TypeError: Cannot read properties of undefined (reading 'interpolate')

  cause Attempting to use `interpolate` or `interpolateTransformSvg` from `d3-interpolate` in the `interpolation` prop without `d3-interpolate` being installed.
  fix Install `d3-interpolate` as a dependency: `npm install d3-interpolate`. Ensure it is imported correctly where used: `import { interpolate } from 'd3-interpolate'`.

• Error: Invalid hook call. Hooks can only be called inside of the body of a function component.

  cause This error often indicates a React version mismatch, specifically using `react-move` v6 (which uses React 16.3+ lifecycle methods) with an older React version (e.g., <16.3.0).
  fix Upgrade your React peer dependency to `^16.3.0` or higher. Alternatively, if upgrading React is not an option, downgrade `react-move` to version 5.x (`npm install react-move@^5.0.0`).

Warnings

• breaking React-Move v6.0.0 (and v3.0.0) requires React 16.3.0 or greater due to the adoption of new lifecycle methods. Using it with older React versions will result in runtime errors related to hooks or component lifecycles.
  Fix: Upgrade your React peer dependency to `^16.3.0` or higher. If you cannot upgrade React, use `react-move@^5.0.0` which includes `react-lifecycles-compat` for broader React version support.
• breaking Since v4.0.0, `d3-interpolate` is no longer a hard dependency. If you require advanced interpolation for non-numeric values (e.g., colors, SVG paths, SVG transforms), you must explicitly install `d3-interpolate` and pass a custom `interpolation` prop to `NodeGroup` or `Animate`.
  Fix: Install `d3-interpolate` via `npm install d3-interpolate` and configure the `interpolation` prop. Refer to the documentation for examples on how to integrate `interpolate` and `interpolateTransformSvg`.
• gotcha Version 5.x of React-Move includes `react-lifecycles-compat` for compatibility with older React versions, which slightly increases the bundle size. For React versions 16.3.0 and newer, using `react-move@^6.0.0` is recommended to get the smallest possible bundle size.
  Fix: If your project uses React 16.3.0 or newer, upgrade to `react-move@^6.0.0` to benefit from the reduced bundle size. If compatibility with older React versions is critical, remain on v5.x.

Install

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

Imports

• NodeGroup
  wrong:

  const { NodeGroup } = require('react-move')

  correct:

  import { NodeGroup } from 'react-move'

  Primary component for animating groups of elements based on data arrays; React-Move v6 is ESM-first.
• Animate
  wrong:

  const Animate = require('react-move').Animate

  correct:

  import { Animate } from 'react-move'

  Component for animating single elements; React-Move v6 is ESM-first.
• NodeGroupProps
  wrong:

  import { NodeGroupProps } from 'react-move'

  correct:

  import type { NodeGroupProps } from 'react-move'

  Importing types for TypeScript; use `type` keyword for type-only imports.

Quickstart

Demonstrates animating a list of SVG circle nodes using `NodeGroup`. It includes dynamic data updates, entry/update/exit animations, and utilizes `d3-interpolate` for advanced SVG transform interpolation.

import React, { useState } from 'react';
import { NodeGroup } from 'react-move';
import { interpolate, interpolateTransformSvg } from 'd3-interpolate';

interface DataItem {
  name: string;
  x: number;
  y: number;
  transform: string;
}

const AnimatedNodes: React.FC = () => {
  const [data, setData] = useState<DataItem[]>([
    { name: 'a', x: 0, y: 0, transform: 'translate(0,0) scale(1)' },
    { name: 'b', x: 50, y: 50, transform: 'translate(50,50) scale(1)' },
  ]);

  const updateData = () => {
    setData(prevData => prevData.map(d => ({
      ...d,
      x: Math.random() * 180 + 10,
      y: Math.random() * 180 + 10,
      transform: `translate(${Math.random() * 100},${Math.random() * 100}) scale(${0.5 + Math.random() * 1.5})`
    })));
  };

  return (
    <div>
      <button onClick={updateData} style={{ marginBottom: '10px' }}>Animate Nodes</button>
      <svg width="200" height="200" style={{ border: '1px solid #eee' }}>
        <NodeGroup
          data={data}
          keyAccessor={(d: DataItem) => d.name}
          start={(data: DataItem) => ({
            x: data.x,
            y: data.y,
            transform: data.transform,
            opacity: 0,
          })}
          enter={(data: DataItem) => ([
            {
              opacity: [1],
              timing: { duration: 500 },
            },
            {
              x: [data.x],
              y: [data.y],
              transform: [data.transform],
              timing: { duration: 500 },
            }
          ])}
          update={(data: DataItem) => ({
            x: [data.x],
            y: [data.y],
            transform: [data.transform],
            opacity: [1],
            timing: { duration: 500, ease: 'easeCubicOut' },
          })}
          leave={() => ([
            {
              opacity: [0],
              timing: { duration: 300 },
            },
            {
              x: [0],
              y: [0],
              timing: { duration: 300 },
            }
          ])}
          interpolation={(begValue, endValue, attr) => {
            if (attr === 'transform') {
              return interpolateTransformSvg(begValue, endValue);
            }
            return interpolate(begValue, endValue);
          }}
        >
          {nodes => (
            <g>
              {nodes.map(({ key, data: item, state }) => (
                <circle
                  key={key}
                  cx={state.x}
                  cy={state.y}
                  r={10}
                  fill="steelblue"
                  opacity={state.opacity}
                  transform={state.transform}
                />
              ))}
            </g>
          )}
        </NodeGroup>
      </svg>
    </div>
  );
};

export default AnimatedNodes;