Motion Animation Library

Common errors

• Module not found: Can't resolve 'framer-motion' in 'your-project-path'

  cause You have installed the new `motion` package but your code still contains `import` statements referencing the deprecated `framer-motion` package.
  fix Globally search and replace all instances of `import ... from 'framer-motion'` with `import ... from 'motion'` or `import ... from 'motion/react'` as appropriate for your code.

• TypeError: (0 , motion_react__WEBPACK_IMPORTED_MODULE_2__.motion) is not a function

  cause This error typically indicates that the `motion` component from `motion/react` was not imported correctly or is being used outside of a valid React component context, often due to an incorrect default vs. named import, or attempting to use vanilla JS `motion` in a React component.
  fix Ensure you are using a named import for the `motion` component: `import { motion } from 'motion/react'`. Also, verify that `motion.div`, `motion.span`, etc., are being rendered within a React component's return statement.

• SyntaxError: Named export 'animate' not found. The requested module 'motion' is a CommonJS module, which may not support all module.exports as named exports.

  cause This error occurs in environments where the bundler or runtime is trying to consume `motion` (an ESM package) as if it were a CommonJS module, and you're trying to destructure named exports from it.
  fix Ensure your build setup or Node.js environment correctly processes ESM. For Node.js, add `"type": "module"` to `package.json`. For bundlers, ensure your configuration is up-to-date and correctly handles module resolution for ESM packages.

Warnings

• breaking The animation library previously known as `framer-motion` has been rebranded and rewritten as `motion`. When migrating, you must update your `package.json` to use `motion` and crucially change all import statements from `framer-motion` to `motion` (for vanilla JS) or `motion/react` (for React components/hooks). Failing to update import paths will result in 'Module not found' errors.
  Fix: Uninstall `framer-motion` (`npm uninstall framer-motion`), install `motion` (`npm install motion`), and then systematically update all import paths in your codebase: `import { ... } from 'framer-motion'` becomes `import { ... } from 'motion/react'` (for React) or `import { ... } from 'motion'` (for vanilla JS).
• gotcha When developing with Motion in a React project, it's critical to import React-specific components and hooks from the `motion/react` subpath. Importing them directly from the base `motion` package will lead to runtime errors or unexpected behavior, as the base package provides vanilla JavaScript utilities not designed for React's component model.
  Fix: Always use `import { motion } from 'motion/react'` for the `motion` component and `import { useSpring } from 'motion/react'` for React hooks. Reserve `import { animate } from 'motion'` for direct DOM manipulation outside of React components.
• gotcha Motion is distributed as an ECMAScript Module (ESM) package. Direct usage in CommonJS environments (e.g., older Node.js scripts or tooling without explicit ESM support) can lead to `SyntaxError: Cannot use import statement outside a module` or similar issues.
  Fix: Ensure your project is configured for ESM. For Node.js, this means setting `"type": "module"` in your `package.json` or using `.mjs` file extensions. For browser applications, use a modern bundler (Vite, Webpack, Rollup) that handles ESM transpilation and resolution.

Install

• npm install motion npm
• yarn add motion yarn
• pnpm add motion pnpm

Imports

• animate
  wrong:

  const { animate } = require('motion')

  correct:

  import { animate } from 'motion'

  Primary function for vanilla JavaScript animations, targeting DOM elements directly. The `motion` package is ESM-first; CommonJS `require` syntax is generally unsupported for direct imports without a transpiler.
• motion (React component)
  wrong:

  import { motion } from 'framer-motion'

  correct:

  import { motion } from 'motion/react'

  This is the core component for animating elements in React. It must be imported from the specific `motion/react` subpath. Importing from `framer-motion` is incorrect after the package rebranding.
• useSpring
  wrong:

  import { useSpring } from 'motion'

  correct:

  import { useSpring } from 'motion/react'

  A widely used hook for creating spring-driven animations within React components. Like the `motion` component, it is specific to the React integration and imported from `motion/react`.
• Variants (type)

  import type { Variants } from 'motion/types'

  TypeScript type definition for configuring animation variants, which are predefined animation states. Use `import type` to ensure it's removed during compilation.

Quickstart

Demonstrates a basic React component utilizing `motion.div` to create an interactive element that animates with a spring effect on hover, showcasing declarative animation syntax.

import { motion } from "motion/react";
import { useState } from 'react';

function AnimatedBox() {
  const [isHovered, setIsHovered] = useState(false);

  return (
    <motion.div
      style={{
        width: '100px',
        height: '100px',
        backgroundColor: isHovered ? '#ff0088' : '#0099ff',
        borderRadius: '10px',
        display: 'flex',
        justifyContent: 'center',
        alignItems: 'center',
        color: 'white',
        cursor: 'pointer'
      }}
      initial={{ x: 0, scale: 1 }}
      animate={{ x: isHovered ? 50 : 0, scale: isHovered ? 1.1 : 1 }}
      transition={{ type: "spring", stiffness: 300, damping: 20 }}
      onHoverStart={() => setIsHovered(true)}
      onHoverEnd={() => setIsHovered(false)}
    >
      Hover Me
    </motion.div>
  );
}

// Example of how you would render this component in a client-side React application:
// import ReactDOM from 'react-dom/client';
// const root = ReactDOM.createRoot(document.getElementById('root') as HTMLElement);
// root.render(<AnimatedBox />);