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.
motion
✓ import { motion } from 'motion/react'
✗ import { motion } from 'framer-motion'
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
✓ import { animate } from 'motion'
✗ import { animate } from 'motion/react'
For vanilla JavaScript projects, import the `animate` function directly from the `motion` package. This provides imperative animation control for DOM elements.
AnimatePresence
✓ import { AnimatePresence } from 'motion/react'
✗ import { AnimatePresence } from 'framer-motion'
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.
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;
Debug
Known issues
breakingThe 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.fixRun `npm uninstall framer-motion` then `npm install motion`. Update imports: `import { ... } from 'framer-motion'` becomes `import { ... } from 'motion/react'`. affects: All versions migrating from `framer-motion` to `motion`
breakingMajor 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.fixConsult the official Motion upgrade guide for specific breaking changes between major versions, especially concerning animation behavior and component lifecycles.
affects: >=3.0
gotchaThe `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.fixVerify your import statements: `import { motion } from 'motion/react'` for React; `import { animate } from 'motion'` for vanilla JavaScript. affects: >=12.0
gotchaMotion 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).fixIf you encounter 'Module not found' errors, explicitly install the peer dependency: `npm install @emotion/is-prop-valid` or `yarn add @emotion/is-prop-valid`.
affects: All versions
Errors
Common errors & fixes
Cannot find module 'framer-motion' or its corresponding type declarations.
The package `framer-motion` has been rebranded to `motion`.
fixUninstall `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.
Incorrect import path for Motion's React components, or attempting to use React-specific features from the vanilla JS import.
fixFor 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.
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.
fixEach `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.
The `@emotion/is-prop-valid` peer dependency or its types are not installed.
fixInstall the missing dependency: `npm install @emotion/is-prop-valid` or `yarn add @emotion/is-prop-valid`.
Audit
Dependencies
reactrequiredPeer dependency required for using Motion with React components.
react-domrequiredPeer dependency required for rendering React components with Motion.
@emotion/is-prop-validrequiredUsed internally by Motion to filter valid DOM props, preventing unknown or custom Motion-specific props from being rendered directly onto HTML/SVG elements. This helps avoid React warnings for unrecognized props.