Motion

Motion (formerly Framer Motion) is an open-source animation library for JavaScript, React, and Vue that combines a hardware-accelerated Web Animations API engine with a JavaScript-powered spring engine to deliver smooth, gesture-driven interfaces without sacrificing bundle size.

Import { motion } from motion/react and existing HTML elements become animatable components with declarative variants, drag, hover, and tap gestures, while the underlying motion-dom and motion-utils packages expose the same primitives to non-React JavaScript projects and the community-maintained Vue port. Shared-layout and scroll-linked animations reuse a FLIP-style projection engine, and split entry points (mini, dom, react-mini) let teams opt into a WAAPI-only build when the full spring engine isn’t needed.

What You Get

• Declarative motion and lightweight m components that turn any HTML/SVG element into an animatable one via animate, variants, whileHover, whileTap, and drag props.
• An imperative animate() function and motion-dom primitives for animating outside React, including scroll-linked (scroll) and viewport (inView) triggers.
• A hybrid engine that automatically chooses between the native Web Animations API and a JS-powered spring engine for hardware-accelerated performance.
• Shared-layout (layout, LayoutGroup) and FLIP-style projection for animating position/size changes between renders without manual measurement code.
• Tree-shakable feature bundles (domAnimation, domMax, domMin, mini, react-mini) so apps only ship the animation capabilities they actually use.

Common Use Cases

• Animating page and modal transitions with AnimatePresence when React components mount and unmount.
• Building drag-to-reorder lists and Kanban boards with the built-in Reorder component and drag gesture primitives.
• Adding scroll-linked parallax and reveal-on-scroll effects to marketing and landing pages via useScroll and scroll.
• Powering shared-element/layout transitions between route or state changes without hand-written FLIP measurement code.

Under The Hood

Architecture The motion package (packages/motion) is a thin re-export shim whose index.ts does export * from "framer-motion/dom", with parallel entry points (dom.ts, mini.ts, react.ts, react-client.ts) mapped to the motion/react-style subpath imports documented in the README. The actual engine lives in framer-motion: packages/framer-motion/src/dom.ts re-exports motion-dom and motion-utils and adds animate, scroll, and inView, while packages/framer-motion/src/index.ts layers on the full React API — the motion and m component proxies (render/components/motion/proxy, render/components/m/proxy), AnimatePresence, LayoutGroup, MotionConfig, Reorder, and motion-value hooks (useMotionValue, useTransform, useSpring, useScroll). Layout/projection logic sits in packages/framer-motion/src/projection and motion-dom/src/projection + motion-dom/src/layout for FLIP-style shared-layout animation. Two animation engines coexist in motion-dom/src/animation — a JS spring/keyframe engine and a native WAAPI engine (animators/waapi) — selected per feature bundle (domAnimation/domMax/domMin in framer-motion/src/render/dom/features-*) so unused capability tree-shakes away. Props flow from the motion/m proxies through VisualState/ScrapeMotionValuesFromProps (render/types.ts) into MotionValues (motion-dom/src/value), which the render/animation pipeline writes to the DOM either via WAAPI or a rAF-driven frameloop (motion-dom/src/frameloop).

Tech Stack TypeScript-first (72.76% of the codebase), managed as a Yarn-workspaces monorepo built with Turborepo (turbo.json) and versioned with Lerna (lerna.json), split into four publishable packages: framer-motion (full React feature set), motion (thin re-export under the current brand), motion-dom (DOM-level animation/gesture/projection/scroll primitives), and motion-utils (dependency-free helpers — clamp, easing, pipe, memoization, error formatting). Peer dependencies are react/react-dom ^18.0.0 || ^19.0.0 plus an optional @emotion/is-prop-valid for prop filtering. The build uses Rollup with Terser minification; tests run on Jest with @testing-library/react, complemented by Playwright and Cypress e2e/visual suites exercised against example harnesses in dev/html, dev/react, dev/next, and dev/react-19. ESLint is extended with eslint-plugin-react-compiler and eslint-plugin-redos-detector to enforce React 19 compiler compatibility and regex-DoS safety.

Code Quality The repo carries 97 colocated test files under framer-motion/src (__tests__ directories alongside animation/, motion/, hooks/) and 66 under motion-dom/src, plus a dedicated __tests__ suite for motion-utils’ pure functions — thorough unit coverage rather than a thin smoke-test layer. Errors route through centralized helpers (motion-utils/src/format-error-message.ts, errors.ts, warn-once.ts) for consistent, de-duplicated dev-mode diagnostics instead of ad hoc throws. Every public export ships a .d.ts via each package’s exports map types condition, and internal modules type MotionValue, ScrapeMotionValuesFromProps, and VisualState explicitly. Naming is consistent (use-* hook files, PascalCase components, kebab-case utilities) and packages are marked "sideEffects": false for correct tree-shaking.

API Design End users mostly just run npm install motion and import { motion } from "motion/react" — one subpath import covers both the JS animate() API and the React component API, with mini/react-mini variants offering smaller bundles when only WAAPI-backed features are needed. The declarative <motion.div animate={{ x: 100 }} /> requires zero boilerplate compared to manually wiring an imperative animation loop, and prop-driven gestures (whileHover, whileTap, drag) read as native HTML props. In-repo documentation is comparatively thin (a ~140-line top-level README plus similarly sized per-package READMEs); the bulk of onboarding material — 330+ examples and 100+ tutorials — lives on the external motion.dev site rather than in the repository itself.