Motion (Animation Library)

Common errors

• Cannot find module 'framer-motion' or its corresponding type declarations.

  cause The package `framer-motion` has been rebranded to `motion`.
  fix Uninstall `framer-motion` and install `motion` (`npm install motion`). Update all import paths from `framer-motion` to `motion/react`.

• `motion.div` is not a function or `motion` is undefined.

  cause Incorrect import path for Motion's React components, or attempting to use React-specific features from the vanilla JS import.
  fix For React components, ensure you are importing `motion` from the correct subpath: `import { motion } from 'motion/react'`.

• Uncaught Error: A MotionValue can only be bound to a single component.

  cause Attempting to pass a `MotionValue` instance (often created with `useMotionValue`) to multiple `motion` components, which is not supported as `MotionValue`s manage state for a single animated property on one component.
  fix Each `motion` component or property that needs an independent `MotionValue` should have its own instance. Re-evaluate your component tree to ensure `MotionValue`s are not shared across props where independent animation is expected.

• TS2307: Cannot find module '@emotion/is-prop-valid' or its corresponding type declarations.

  cause The `@emotion/is-prop-valid` peer dependency or its types are not installed.
  fix Install the missing dependency: `npm install @emotion/is-prop-valid` or `yarn add @emotion/is-prop-valid`.

Warnings

• breaking The package has been rebranded from `framer-motion` to `motion`. Existing projects must uninstall `framer-motion` and install `motion`, then update all import paths from `framer-motion` to `motion/react` for React components. The old package is no longer actively developed.
  Fix: Run `npm uninstall framer-motion` then `npm install motion`. Update imports: `import { ... } from 'framer-motion'` becomes `import { ... } from 'motion/react'`.
• breaking Major versions of Framer Motion (e.g., v3.0) included specific breaking changes related to velocity calculation, render scheduling, and `AnimatePresence` behavior. While the current `motion` package is at v12+, be mindful of detailed upgrade guides when moving between significant versions.
  Fix: Consult the official Motion upgrade guide for specific breaking changes between major versions, especially concerning animation behavior and component lifecycles.
• gotcha The `motion` package now serves multiple platforms (React, vanilla JS, Vue via `motion-v`). Ensure you are using the correct import path for your environment (`motion/react` for React, `motion` for vanilla JS) to avoid errors or unintended behavior.
  Fix: Verify your import statements: `import { motion } from 'motion/react'` for React; `import { animate } from 'motion'` for vanilla JavaScript.
• gotcha Motion has a peer dependency on `@emotion/is-prop-valid`. While package managers often handle peer dependencies, you might encounter 'Module not found' warnings or errors if this dependency is not explicitly installed or if your build setup is unusual (e.g., in some monorepo configurations or older bundlers).
  Fix: If you encounter 'Module not found' errors, explicitly install the peer dependency: `npm install @emotion/is-prop-valid` or `yarn add @emotion/is-prop-valid`.

Install

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

Imports

• motion
  wrong:

  import { motion } from 'framer-motion'

  correct:

  import { motion } from 'motion/react'

  For React projects, use the `motion/react` subpath. The `framer-motion` package name and import path are deprecated in favor of `motion` and `motion/react` since the rebranding.
• animate
  wrong:

  import { animate } from 'motion/react'

  correct:

  import { animate } from 'motion'

  For vanilla JavaScript projects, import the `animate` function directly from the `motion` package. This provides imperative animation control for DOM elements.
• AnimatePresence
  wrong:

  import { AnimatePresence } from 'framer-motion'

  correct:

  import { AnimatePresence } from 'motion/react'

  This component is essential for animating components as they unmount from the DOM (exit animations) or enter/exit lists in React. Always import from `motion/react` for React projects.

Quickstart

This quickstart demonstrates a basic animated React component using Motion, showcasing initial and animate props, custom transitions, and interactive `whileHover`/`whileTap` gestures.

import React from 'react';
import { motion } from 'motion/react';

function AnimatedBox() {
  return (
    <motion.div
      initial={{ opacity: 0, x: -100 }}
      animate={{ opacity: 1, x: 0 }}
      transition={{
        duration: 0.8,
        delay: 0.2,
        ease: [0, 0.71, 0.2, 1.01]
      }}
      style={{
        width: '100px',
        height: '100px',
        backgroundColor: '#61dafb',
        borderRadius: '10px',
        display: 'flex',
        justifyContent: 'center',
        alignItems: 'center',
        fontSize: '1.2rem',
        color: 'white',
        cursor: 'pointer'
      }}
      whileHover={{ scale: 1.1, backgroundColor: '#282c34' }}
      whileTap={{ scale: 0.9 }}
    >
      Hello Motion!
    </motion.div>
  );
}

export default AnimatedBox;