React Lifecycle Motion

Common errors

• ReferenceError: CSSMotion is not defined

  cause Incorrect import statement for the CSSMotion component.
  fix Use a named import: `import { CSSMotion } from 'rc-motion';`

• Warning: Function components cannot be given refs. Attempts to access this ref will fail. Did you mean to use React.forwardRef()?

  cause A functional component passed as a child to CSSMotion is attempting to receive a ref directly.
  fix Wrap the child functional component with `React.forwardRef` to allow it to correctly receive and forward refs.

• Element persists in the DOM after its leave animation finishes, even if it's no longer visible.

  cause The `removeOnLeave` prop is not enabled, or a bug in older versions prevents proper cleanup.
  fix Set the `removeOnLeave` prop on `CSSMotion` to `true`. If the issue persists with `rc-motion@2.9.5`, consider migrating to `@rc-component/motion`.

• TypeError: Cannot read properties of undefined (reading 'className') (or 'style')

  cause The render prop function for `CSSMotion` is not correctly destructuring and passing the `className` or `style` props to the rendered element.
  fix Ensure your render prop looks like `{({ className, style }) => <div className={className} style={style} />}` to correctly apply the motion styles.

Warnings

• breaking The `rc-motion` package has been renamed and its active development moved to `@rc-component/motion`. While `rc-motion@2.9.5` is still available, new features and bug fixes are primarily released under the `@rc-component/motion` namespace (v1.x and above).
  Fix: Consider migrating to `@rc-component/motion` for continued support and updates. Be aware of potential API differences during migration, though core functionality is largely similar.
• deprecated The `rc-motion` package itself is considered deprecated. Its last major update (v2.9.5) was over two years ago. For actively maintained code, developers should transition to `@rc-component/motion`.
  Fix: Update your package dependencies from `rc-motion` to `@rc-component/motion` and review its changelog for any breaking changes introduced in its 1.x releases.
• gotcha Older versions of `rc-motion` (before fixes in `@rc-component/motion` v1.1.6) might exhibit 'DOM residue' where elements are not correctly removed from the DOM after leave animations, especially on re-activation or rapid toggling.
  Fix: Ensure `removeOnLeave` prop is set to `true`. If issues persist, consider updating to `@rc-component/motion` which has addressed these types of bugs.
• gotcha Issues with ref forwarding to children wrapped by `CSSMotion` have been observed and fixed in later versions of `@rc-component/motion`. If you pass a ref directly to a functional child component within `CSSMotion`, it might not work as expected.
  Fix: Ensure that any child component receiving a ref is either a class component or a functional component wrapped with `React.forwardRef`. If using an older `rc-motion` version, this might require manual ref handling or migrating to `@rc-component/motion` for the fixes.

Install

• npm install rc-motion npm
• yarn add rc-motion yarn
• pnpm add rc-motion pnpm

Imports

• CSSMotion
  wrong:

  import CSSMotion from 'rc-motion';

  correct:

  import { CSSMotion } from 'rc-motion';

  CSSMotion is a named export. Default import will result in 'undefined' or a different module object.
• CSSMotionList
  wrong:

  const CSSMotionList = require('rc-motion').CSSMotionList;

  correct:

  import { CSSMotionList } from 'rc-motion';

  While CommonJS require syntax might work, ESM named imports are the standard for modern React applications. The package ships TypeScript types for enhanced development.
• CSSMotionProps
  wrong:

  import { CSSMotionProps } from 'rc-motion';

  correct:

  import type { CSSMotionProps } from 'rc-motion';

  When importing types in TypeScript, use 'import type' for clarity and to ensure type-only imports are correctly handled during transpilation.

Quickstart

Demonstrates basic usage of CSSMotion with state-driven visibility, custom motion classes, and lifecycle callbacks.

import React, { useState } from 'react';
import { CSSMotion } from 'rc-motion';

function MyAnimatedComponent() {
  const [visible, setVisible] = useState(true);

  return (
    <div>
      <button onClick={() => setVisible(prev => !prev)}>
        Toggle Motion
      </button>
      <CSSMotion
        visible={visible}
        motionName="my-fade"
        onAppearStart={() => console.log('Appear Start')}
        onAppearActive={() => console.log('Appear Active')}
        onAppearEnd={() => console.log('Appear End')}
        onEnterStart={() => console.log('Enter Start')}
        onEnterActive={() => console.log('Enter Active')}
        onEnterEnd={() => console.log('Enter End')}
        onLeaveStart={() => console.log('Leave Start')}
        onLeaveActive={() => console.log('Leave Active')}
        onLeaveEnd={() => console.log('Leave End')}
        removeOnLeave={true}
      >
        {({ className, style }) => (
          <div
            className={className}
            style={{ ...style, padding: '20px', border: '1px solid blue', backgroundColor: 'lightblue' }}
          >
            Hello, Motion!
          </div>
        )}
      </CSSMotion>
    </div>
  );
}

export default MyAnimatedComponent;