Motion Animation Library

name: motion description: | Production-ready setup for Motion (formerly Framer Motion) - the most popular React animation library with 30,200+ GitHub stars. Motion provides declarative animations, gesture controls, scroll-based effects, spring physics, layout animations, and SVG manipulation.

This skill should be used when building UIs that need complex animations beyond simple list transitions: gesture controls (drag, hover, tap), scroll-linked animations, parallax effects, shared element transitions, SVG path morphing, spring physics, or orchestrated animation sequences.

Use when: Adding drag-and-drop interactions, creating scroll-triggered animations, implementing modal dialogs with sophisticated transitions, building carousels with momentum, animating page/route transitions, creating hero sections with parallax, implementing accordion components with smooth expand/collapse, or optimizing animation bundle size with LazyMotion.

Important: For simple list add/remove/sort animations, use the auto-animate skill instead (3.28 KB vs 34 KB bundle). Motion is designed for complex interactive animations that require fine-grained control.

license: MIT

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)

Production Tested: React 19, Next.js 15, Vite 6, 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 skill instead:

• Todo list add/remove (auto-animate: 3.28 KB vs motion: 34 KB)
• Search results filtering
• Shopping cart items
• Notification toasts
• Basic accordions without gestures

Static Content:

• No user interaction or animations needed
• Server-rendered content without client interactivity

Cloudflare Workers Deployment → Known Issue:

• Motion has build compatibility issues with Wrangler (GitHub issue #2918)
• Workaround: Use framer-motion v12.23.24 instead (same API, works with Workers)

3D Animations → Use dedicated 3D library:

• Three.js for WebGL
• React Three Fiber for React + Three.js

Installation

Latest Stable Version

# Using pnpm (recommended)
pnpm add motion

# Using npm
npm install motion

# Using yarn
yarn add motion

Current Version: 12.23.24 (verified 2025-11-07)

Alternative for Cloudflare Workers:

# Use framer-motion if deploying to Cloudflare Workers
pnpm add framer-motion

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:

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>

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:

const container = {
  hidden: { opacity: 0 },
  show: {
    opacity: 1,
    transition: {
      staggerChildren: 0.1, // Delay between each child
      delayChildren: 0.2,   // Initial delay before children
    }
  }
}

const item = {
  hidden: { opacity: 0, y: 20 },
  show: { opacity: 1, y: 0 }
}

<motion.ul variants={container} initial="hidden" animate="show">
  {items.map(item => (
    <motion.li key={item.id} variants={item}>
      {item.text}
    </motion.li>
  ))}
</motion.ul>

Benefits:

• Clean, declarative API
• Automatic choreography (stagger, delay, sequence)
• Reusable animation states
• Reduced prop drilling

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>

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):

// ❌ 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>

How it works:

• Calculates First position before change
• Applies change immediately (Last position)
• Inverts transform to match first position
• Plays animation to last position

Special Props:

• layoutId: Connect separate elements for shared transitions
• layoutScroll: Fix animations in scrollable containers
• layoutRoot: Fix animations in fixed-position elements

5. Scroll Animations

Viewport-Triggered (whileInView)

<motion.div
  initial={{ opacity: 0, y: 50 }}
  whileInView={{ opacity: 1, y: 0 }}
  viewport={{ once: true, margin: "-100px" }}
>
  Fades in when