Summary 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 supportScroll Animations : viewport-triggered, scroll-linked, parallax effectsLayout Animations : FLIP technique for smooth layout changes, shared element transitionsSpring Physics : Natural, customizable motion with physics-based easingSVG : Path morphing, line drawing, attribute animationExit Animations : AnimatePresence for unmounting transitionsPerformance : 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
SVG line drawing animations
Path morphing between shapes
Spring physics for natural bounce
Orchestrated sequences (staggered reveals)
Modal dialogs with backdrop blur
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 interactionsCloudflare 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 bun add motion # preferred
# or: npm install motion
# or: yarn add motion
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 :
# Use framer-motion if deploying to Cloudflare Workers
bun add framer-motion
# or: npm install framer-motion
Package Information
Bundle Size :
Full motion component: ~34 KB minified+gzipped
LazyMotion + m component: ~4.6 KBuseAnimate 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:
import { motion } from "motion/react"
// Basic animation
<motion.div
initial={{ opacity: 0, y: 20 }}
animate={{ opacity: 1, y: 0 }}
transition={{ duration: 0.5 }}
>
Content fades in and slides up
</motion.div>
// Gesture controls
<motion.button
whileHover={{ scale: 1.1 }}
whileTap={{ scale: 0.95 }}
>
Click me
</motion.button>
initial: Starting state (object or variant name)animate: Target state (object or variant name)exit: Unmounting state (requires AnimatePresence)transition: Timing/easing configurationwhileHover, whileTap, whileFocus: Gesture stateswhileInView: Viewport-triggered animationdrag: 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:
const variants = {
hidden: { opacity: 0, y: 20 },
visible: { opacity: 1, y: 0 }
}
<motion.div variants={variants} initial="hidden" animate="visible">
Content
</motion.div>
For advanced orchestration (staggerChildren, delayChildren, dynamic variants), load references/core-concepts-deep-dive.md.
3. AnimatePresence (Exit Animations) Enables animations when components unmount:
import { AnimatePresence } from "motion/react"
<AnimatePresence>
{isVisible && (
<motion.div
key="modal"
initial={{ opacity: 0 }}
animate={{ opacity: 1 }}
exit={{ opacity: 0 }}
>
Modal content
</motion.div>
)}
</AnimatePresence>
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):
// ❌ Wrong - AnimatePresence unmounts with condition
{isVisible && (
<AnimatePresence>
<motion.div>Content</motion.div>
</AnimatePresence>
)}
// ✅ Correct - AnimatePresence stays mounted
<AnimatePresence>
{isVisible && <motion.div key="unique">Content</motion.div>}
</AnimatePresence>
4. Layout Animations (FLIP) Automatically animate layout changes:
<motion.div layout>
{isExpanded ? <FullContent /> : <Summary />}
</motion.div>
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 // Viewport-triggered
<motion.div
initial={{ opacity: 0, y: 50 }}
whileInView={{ opacity: 1, y: 0 }}
viewport={{ once: true }}
>
Fades in when entering viewport
</motion.div>
// Scroll-linked (parallax)
import { useScroll, useTransform } from "motion/react"
const { scrollYProgress } = useScroll()
const y = useTransform(scrollYProgress, [0, 1], [0, -300])
<motion.div style={{ y }}>Parallax effect</motion.div>
For advanced scroll patterns (useScroll offsets, useTransform easing, parallax layers), load references/core-concepts-deep-dive.md.
6. Gestures <motion.div drag="x" dragConstraints={{ left: -200, right: 200 }}>
Drag me
</motion.div>
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 <motion.div
animate={{ x: 100 }}
transition={{ type: "spring", stiffness: 100, damping: 10 }}
/>
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
"use client"
import { motion } from "motion/react"
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):
import { LazyMotion, domAnimation, m } from "motion/react"
<LazyMotion features={domAnimation}>
<m.div>Only 4.6 KB!</m.div>
</LazyMotion>
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 :
import { MotionConfig } from "motion/react"
<MotionConfig reducedMotion="user">
<App />
</MotionConfig>
Keyboard Support : Use whileFocus for keyboard-triggered animations.
<motion.button whileFocus={{ scale: 1.1 }} tabIndex={0}>
Keyboard accessible
</motion.button>
For complete accessibility guide (ARIA patterns, screen readers, AnimatePresence workaround, testing), load references/accessibility-guide.md.
Common Patterns Modal Dialog (AnimatePresence + backdrop):
<AnimatePresence>
{isOpen && (
<motion.dialog exit={{ opacity: 0 }}>Content</motion.dialog>
)}
</AnimatePresence>
Accordion (height animation):
<motion.div animate={{ height: isOpen ? "auto" : 0 }}>
Content
</motion.div>
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):
// ❌ Wrong
{isVisible && <AnimatePresence><motion.div>Content</motion.div></AnimatePresence>}
// ✅ Correct
<AnimatePresence>
{isVisible && <motion.div key="unique">Content</motion.div>}
</AnimatePresence>
Issue 2: Next.js "use client" Missing Symptom : Build fails with "motion is not defined" or SSR errors.
Solution : Add "use client" directive:
"use client"
import { motion } from "motion/react"
Issue 3: Tailwind Transitions Conflict Symptom : Animations stutter or don't work.
Solution : Remove transition-* classes (Motion overrides CSS transitions):
// ❌ Wrong: <motion.div className="transition-all" animate={{ x: 100 }} />
// ✅ Correct: <motion.div animate={{ x: 100 }} />
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):
bun add framer-motion # Same API, works with Workers
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:
motion-vite-basic.tsx - Basic Vite + React + TypeScript setup with common animationsmotion-nextjs-client.tsx - Next.js App Router pattern with client component wrapperscroll-parallax.tsx - Scroll animations, parallax, and viewport triggersui-components.tsx - Modal, accordion, carousel, tabs with shared underlinelayout-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 AutoAnimateperformance-optimization.md - Bundle size, LazyMotion, virtualization, hardware accelerationnextjs-integration.md - App Router vs Pages Router, "use client", known issuescommon-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 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 suggestion?
Recommended Stack : ✅ React 19 + Next.js 16 + Vite 7 + Tailwind v4
Token Savings : ~83%
Error Prevention : 100% (29+ documented errors prevented)
Bundle Size : 2.3 KB (mini) - 34 KB (full), optimizable to 4.6 KB with LazyMotion
Accessibility : MotionConfig reducedMotion support
Ready to use! Install with /plugin install motion@claude-skills
