Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
animate
✓ import { animate } from 'motion'
✗ const { animate } = require('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)
✓ import { motion } from 'motion/react'
✗ import { motion } from 'framer-motion'
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
✓ import { useSpring } from 'motion/react'
✗ import { useSpring } from 'motion'
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.
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 />);
Debug
Known issues
breakingThe 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.fixUninstall `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). affects: All versions of `motion` (when migrating from `framer-motion` to the new package)
gotchaWhen 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.fixAlways 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. affects: >=1.0.0
gotchaMotion 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.fixEnsure 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.
affects: >=1.0.0
Errors
Common errors & fixes
Module not found: Can't resolve 'framer-motion' in 'your-project-path'
You have installed the new `motion` package but your code still contains `import` statements referencing the deprecated `framer-motion` package.
fixGlobally 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
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.
fixEnsure 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.
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.
fixEnsure 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.
Audit
Dependencies
@emotion/is-prop-validoptionalUsed internally by Motion for React to filter props, preventing React from rendering non-standard HTML attributes. While marked as an optional peer dependency, it is highly recommended for proper functioning and avoiding warnings when using Motion with React.
reactrequiredRequired for Motion's React integration (`motion/react`) to function correctly, enabling component-based animations and hooks. Specifies broad compatibility with React 18 and 19.
react-domrequiredRequired for Motion's React integration (`motion/react`) for efficient rendering and interaction with the DOM. Specifies broad compatibility with React 18 and 19.