Motion (Framer Motion) React animation library. Use for drag-and-drop, scroll animations, gestures, SVG morphing, or encountering bundle size, complex transitions, spring physics errors.

Motion Animation Library Overview Motion (package: motion , formerly framer motion ) is the industry standard React animation library used in production by thousands of applications. With 30,200+ GitHub stars and 300+ official examples, it provides a declarative API for creating sophisticated animations with minimal code. Key Capabilities: Gestures : drag, hover, tap, pan, focus with cross device support Scroll Animations : viewport triggered, scroll linked, parallax effects Layout Animations : FLIP technique for smooth layout changes, shared element transitions Spring Physics : Natural, customizable motion with physics based easing SVG : Path morphing, line drawing, attribute animation Exit Animations : AnimatePresence for unmounting transitions Performance : Hardware accelerated, ScrollTimeline API, bundle optimization (2.3 KB 34 KB) Recommended Stack : React 19, Next.js 16, Vite 7, Tailwind v4 When to Use This Skill ✅ Use Motion When: Complex Interactions : Drag and drop interfaces (sortable lists, kanban boards, sliders) Hover states with scale/rotation/color changes Tap feedback with bounce/squeeze effects Pan gestures for mobile friendly controls Scroll Based Animations : Hero sections with parallax layers Scroll triggered reveals (fade in as elements enter viewport) Progress bars linked to scroll position Sticky headers with scroll dependent transforms Layout Transitions : Shared element transitions between routes (card → detail page) Expand/collapse with automatic height animation Grid/list view switching with smooth repositioning Tab navigation with animated underline Advanced Features : SVG line drawing animations Path morphing between shapes Spring physics for natural bounce Orchestrated sequences (staggered reveals) Modal dialogs with backdrop blur Bundle Optimization : Need 2.3 KB animation library (useAnimate mini) Want to reduce Motion from 34 KB to 4.6 KB (LazyMotion) ❌ Don't Use Motion When: Simple list animations (use auto animate instead: 3.28 KB vs 34 KB) Static content without interactions Cloudflare Workers (historically needed the framer motion alias; with motion v12.43+ the main package works on Workers — see Known Issues) 3D animations (use Three.js or React Three Fiber instead) Installation Latest Stable Version Current Version : 12.43.0 (verified 2026 08 03) Note : motion is the current package name. framer motion is a deprecated alias that republishes the same code; it still works and is maintained as an install time alias (notably useful as a Cloudflare Workers build workaround), but new projects should install motion . Alternative for Cloudflare Workers : Package Information Bundle Size : Full motion component: ~34 KB minified+gzipped LazyMotion + m component: ~4.6 KB useAnimate mini: 2.3 KB (smallest React animation library) useAnimate hybrid: 17 KB Dependencies : React 18+ or React 19+ TypeScript : Native support included (no @types package needed) Core Concepts 1. The motion Component Transform any HTML/SVG element into an animatable component: Props: initial : Starting state (object or variant name) animate : Target state (object or variant name) exit : Unmounting state (requires AnimatePresence) transition : Timing/easing configuration whileHover , whileTap , whileFocus : Gesture states whileInView : Viewport triggered animation drag : Enable dragging ("x", "y", or true for both) layout : Enable FLIP layout animations 2. Variants (Animation Orchestration) Named animation states that propagate through component tree: For advanced orchestration (staggerChildren, delayChildren, dynamic variants), load references/core concepts deep dive.md . 3. AnimatePresence (Exit Animations) Enables animations when components unmount: Critical Rules: AnimatePresence must stay mounted (don't wrap in conditional) All children must have unique key props AnimatePresence wraps the conditional , not the other way around Common Mistake (exit animation won't play): 4. Layout Animations (FLIP) Automatically animate layout changes: Special props : layoutId (shared element transitions), layoutScroll (scrollable containers), layoutRoot (fixed positioning). For advanced patterns (LayoutGroup, layoutId orchestration), load references/core concepts deep dive.md . 5. Scroll Animations For advanced scroll patterns (useScroll offsets, useTransform easing, parallax layers), load references/core concepts deep dive.md . 6. Gestures Available : whileHover , whileTap , whileFocus , whileDrag , whileInView , drag . For advanced drag controls (momentum, elastic, event handlers), load references/core concepts deep dive.md . 7. Spring Physics Common presets : Bouncy { stiffness: 300, damping: 10 } , Smooth { stiffness: 100, damping: 20 } . For spring tuning (mass, visualizer, presets), load references/core concepts deep dive.md . Integration Guides Vite : bun add motion → import { motion } from "motion/react" (works out of the box) Next.js App Router : Requires "use client" directive or client component wrapper Tailwind : ⚠️ Remove transition classes (causes conflicts with Motion animations) Cloudflare Workers : Use framer motion v12.43.0 instead (Motion has Wrangler build issues) For complete integration guides (Next.js patterns, SSR, framework specific issues), load references/nextjs integration.md . Performance Optimization Bundle Size : Use LazyMotion (34 KB → 4.6 KB): Large Lists : Use virtualization ( react window , react virtuoso ) for 50+ animated items. For complete optimization guide (hardware acceleration, memory profiling, production benchmarks), load references/performance optimization.md . Accessibility Respect prefers reduced motion : Keyboard Support : Use whileFocus for keyboard triggered animations. For complete accessibility guide (ARIA patterns, screen readers, AnimatePresence workaround, testing), load references/accessibility guide.md . Common Patterns Modal Dialog (AnimatePresence + backdrop): Accordion (height animation): For 15+ production patterns (carousel, tabs, scroll reveal, parallax, notifications), load references/common patterns.md . Known Issues & Solutions Issue 1: AnimatePresence Exit Not Working (MOST COMMON) Symptom : Components disappear instantly without exit animation. Solution : AnimatePresence must stay mounted, wrap the conditional (not be wrapped by it): Issue 2: Next.js "use client" Missing Symptom : Build fails with "motion is not defined" or SSR errors. Solution : Add "use client" directive: Issue 3: Tailwind Transitions Conflict Symptom : Animations stutter or don't work. Solution : Remove transition classes (Motion overrides CSS transitions): Issue 4: Cloudflare Workers Build Errors Symptom : Wrangler build fails when using motion package. Solution : Use framer motion v12.43.0 instead (GitHub issue 2918): Issue 5: Large List Performance Symptom : 50 100+ animated items cause severe slowdown. Solution : Use virtualization ( react window , react virtuoso ). For 5+ additional issues (layoutScroll, layoutRoot, AnimatePresence + layoutId), load references/nextjs integration.md or references/core concepts deep dive.md . When to Load References Claude should load these references based on user needs: Load references/core concepts deep dive.md when: User asks about variants orchestration (staggerChildren, delayChildren, dynamic variants) User needs advanced layout animations (layoutId shared transitions, LayoutGroup) User wants scroll linked animations (useScroll offsets, useTransform easing, parallax layers) User needs complex drag patterns (momentum, elastic, event handlers, constraints) User asks about spring physics tuning (mass parameter, visualizer, custom presets) Load references/performance optimization.md when: User wants to reduce bundle size below 4.6 KB (useAnimate mini, LazyMotion comparison) User mentions "app is slow", "janky animations", "laggy", or "performance issues" User has 50+ animated items in a list (virtualization needed) User needs memory profiling or production benchmarks Load references/nextjs integration.md when: User is building with Next.js (App Router or Pages Router) User encounters SSR errors, "use client" errors, or hydration issues User asks about route transitions or page navigation animations User needs Next.js specific workarounds (Reorder component, AnimatePresence soft navigation) Load references/accessibility guide.md when: User asks about "prefers reduced motion" or accessibility compliance User needs ARIA integration patterns (roles, labels, announcements) User wants screen reader compatibility User mentions accessibility audits or WCAG compliance User asks about AnimatePresence reducedMotion workaround (known issue 1567) Load references/common patterns.md when: User asks for specific UI patterns (modal, accordion, carousel, tabs, dropdown, toast, etc.) User needs copy paste code examples for production use User wants to see 15+ real world animation patterns Load references/motion vs auto animate.md when: User is deciding between Motion and AutoAnimate libraries User mentions "simple list animations" or "bundle size concerns" User asks "which animation library should I use?" or "is Motion overkill?" User needs feature comparison or decision matrix Templates This skill includes 5 production ready templates in the templates/ directory: 1. motion vite basic.tsx Basic Vite + React + TypeScript setup with common animations 2. motion nextjs client.tsx Next.js App Router pattern with client component wrapper 3. scroll parallax.tsx Scroll animations, parallax, and viewport triggers 4. ui components.tsx Modal, accordion, carousel, tabs with shared underline 5. layout transitions.tsx FLIP layout animations and shared element transitions Copy templates into your project and customize as needed. References This skill includes 4 comprehensive reference guides: motion vs auto animate.md Decision guide: when to use Motion vs AutoAnimate performance optimization.md Bundle size, LazyMotion, virtualization, hardware acceleration nextjs integration.md App Router vs Pages Router, "use client", known issues common patterns.md Top 15 patterns with full code examples See references/ directory for detailed guides. Scripts This skill includes 2 automation scripts: init motion.sh One command setup with framework detection (Vite, Next.js, Cloudflare Workers) optimize bundle.sh Convert existing Motion code to LazyMotion for smaller bundle See scripts/ directory for automation tools. Official Documentation Official Site : https://motion.dev GitHub : https://github.com/motiondivision/motion (30,200+ stars) Examples : https://motion.dev/examples (300+ examples) Related Skills : auto animate (simple lists), tailwind v4 shadcn (styling), nextjs (App Router), cloudflare worker base Motion vs AutoAnimate : Load references/motion vs auto animate.md for detailed comparison. Token Efficiency Metrics Token Savings : ~83% (30k → 5k tokens) Error Prevention : 100% (29+ errors) Time Savings : ~85% (2 3 hrs → 20 30 min) Package Versions (Verified 2026 08 03) Package Version Status motion 12.43.0 ✅ Latest stable framer motion 12.43.0 ✅ Deprecated alias of motion (Cloudflare Workers workaround) react 19.2.0 ✅ Latest stable vite 7.3.0 ✅ Latest stable Contributing Found an issue or have a suggest