Motion

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)

Production Tested: React 19.2, Next.js 16.1, Vite 7.3, 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 → ✅ Fixed (Dec 2024):

• Previous build compatibility issues resolved (GitHub issue #2918 closed as completed)
• Motion now works directly with Wrangler - no workaround needed
• Both motion and framer-motion v12.23.24 work correctly

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.27.5 (verified 2026-01-21)

Note for Cloudflare Workers:

# Both packages work with Cloudflare Workers (issue #2918 fixed Dec 2024)
pnpm add motion
# OR
pnpm add framer-motion  # Same version, same API

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. AnimatePresence (Exit Animations)

Enables animations when components unmount:

import { AnimatePresence } from "motion/react"

  {isVisible && (
    
      Modal content
    
  )}

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 && (
  
    Content
  
)}

// ✅ Correct - AnimatePresence stays mounted

  {isVisible && Content}

2. Layout Animations

Special Props:

• layout: Enable FLIP layout animations
• layoutId: Connect separate elements for shared transitions
• layoutScroll: Fix animations in scrollable containers (see Issue #5)
• layoutRoot: Fix animations in fixed-position elements (see Issue #7)

  {isExpanded ?  : }

3. Scroll Animations

Viewport-Triggered (whileInView)

  Fades in when 100px from entering viewport

Scroll-Linked (useScroll)

import { useScroll, useTransform } from "motion/react"

const { scrollYProgress } = useScroll()
const y = useTransform(scrollYProgress, [0, 1], [0, -300])

  Moves up 300px as user scrolls page

Performance: Uses native ScrollTimeline API when available for hardware acceleration.

---

Integration Guides

Vite + React + TypeScript

pnpm add motion

Import: import { motion } from "motion/react"

No Vite configuration needed - works out of the box.

Next.js App Router (Recommended Pattern)

Key Requirement: Motion only works in Client Components (not Server Components).

Step 1: Create Client Component Wrapper

src/components/motion-client.tsx:

"use client"

// Optimized import for Next.js (reduces client JS)
import * as motion from "motion/react-client"

export { motion }

Step 2: Use in Server Components

src/app/page.tsx:

import { motion } from "@/components/motion-client"

export default function Page() {
  return (
    
      This works in Server Component (wrapper is client)
    
  )
}

Alternative: Direct Client Component

"use client"

import { motion } from "motion/react"

export function AnimatedCard() {
  return ...
}

Known Issues (Next.js 15+ + React 19):

• React 19 fully supported as of December 2025 (see Issue #11 for one StrictMode edge case)
• Most compatibility issues resolved in Motion 12.27.5
• AnimatePresence may fail with soft navigation
• Reorder component incompatible with Next.js routing and page-level scrolling (see Issue #10)

Next.js Pages Router

Works without modifications:

import { motion } from "motion/react"

export default function Page() {
  return No "use client" needed
}

Tailwind CSS Integration

Best Practice: Let each library do what it does best.

• Tailwind: Static and responsive styling via className
• Motion: Animations via motion props

  Tailwind styles + Motion animations

⚠️ Remove Tailwind Transitions: Causes stuttering/conflicts.

// ❌ Wrong - Tailwind transition conflicts with Motion

// ✅ Correct - Remove Tailwind transition

Why: Motion uses inline styles or native browser animations, both override Tailwind's CSS transitions.

Cloudflare Workers (✅ Now Supported)

Status: ✅ Fixed as of December 2024 (GitHub issue #2918 closed as completed)

Installation:

# Motion now works directly with Cloudflare Workers
pnpm add motion

Import:

import { motion } from "motion/react"

Historical Note: Prior to December 2024, there was a Wrangler ESM resolution issue requiring use of framer-motion as a workaround. This has been resolved, and both packages now work correctly with Cloudflare Workers.

---

Performance Optimization

1. Reduce Bundle Size with LazyMotion

Problem: Full motion component is ~34 KB minified+gzipped.

Solution: Use LazyMotion + m component for 4.6 KB:

import { LazyMotion, domAnimation, m } from "motion/react"

function App() {
  return (
    
      {/* Use 'm' instead of 'motion' */}
      
        Only 4.6 KB!
      
    
  )
}

How it works: Loads animation features on-demand instead of bundling everything.

Alternative (Smallest): useAnimate mini (2.3 KB):

import { useAnimate } from "motion/react"

function Component() {
  const [scope, animate] = useAnimate()

  return Smallest possible React animation
}

2. Hardware Acceleration

Add willChange for transforms:

Also add for: opacity, backgroundColor, clipPath, filter

How it works: Tells browser to optimize for animation, uses GPU compositing.

3. Large Lists → Use Virtualization

Problem: Animating 50-100+ items causes severe slowdown.

Solutions:

pnpm add react-window
# or
pnpm add react-virtuoso
# or
pnpm add @tanstack/react-virtual

Pattern:

import { FixedSizeList } from 'react-window'
import { motion } from 'motion/react'

  {({ index, style }) => (
    
      Item {index}
    
  )}

Why: Only renders visible items, reduces DOM updates and memory usage.

4. Use layout Prop for FLIP Animations

Automatically animates layout changes without JavaScript calculation:

  {isExpanded ?  : }

Performance: Hardware-accelerated via transforms, no reflow/repaint.

---

Accessibility

Respect prefers-reduced-motion

import { MotionConfig } from "motion/react"

  

Options:

• "user": Respects OS setting (recommended)
• "always": Force instant transitions
• "never": Ignore user preference

Note: ✅ Fixed in Jan 2023 (GitHub #1567) - MotionConfig now works correctly with AnimatePresence.

---

Common Patterns

5 Production-Ready Patterns:

1. Modal Dialog - AnimatePresence with backdrop + dialog exit animations
2. Accordion - Animate height with height: "auto"
3. Drag Carousel - drag="x" with dragConstraints
4. Scroll Reveal - whileInView with viewport margin
5. Parallax Hero - useScroll + useTransform for layered effects

See references/common-patterns.md for full code (15+ patterns).

---

Known Issues & Solutions

Issue 1: AnimatePresence Exit Not Working

Error: Exit animations don't play, components disappear instantly Source: GitHub Issue #3078

Why It Happens: AnimatePresence wrapped in conditional or missing key props. Defining exit props on staggered children inside modals can also prevent modal from unmounting (backdrop remains visible).

Solution:

// ❌ Wrong - AnimatePresence wrapped in conditional
{isVisible && (
  
    Content
  
)}

// ✅ Correct - AnimatePresence stays mounted

  {isVisible && Content}

// ❌ Wrong - Staggered children with exit prevent modal removal

  {isOpen && (
    
      
        {items.map(item => (
          
            {item.content}
          
        ))}
      
    
  )}

// ✅ Fix for modal - Remove exit from children or set duration: 0

  {item.content}

Issue 2: Large List Performance

Symptom: 50-100+ animated items cause severe slowdown, browser freezes.

Solution: Use virtualization:

pnpm add react-window

See references/performance-optimization.md for full guide.

Issue 3: Tailwind Transitions Conflict

Symptom: Animations stutter or don't work.

Solution: Remove transition-* classes:

// ❌ Wrong

// ✅ Correct

Issue 4: 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"

See references/nextjs-integration.md for App Router patterns.

Issue 5: Scrollable Container Layout Animations

Symptom: Incomplete transitions when removing items from scrolled containers.

Solution: Add layoutScroll prop:

  {items.map(item => (
    
      {item.content}
    
  ))}

Issue 6: Cloudflare Workers Build Errors (✅ RESOLVED)

Status: ✅ Fixed in December 2024 (GitHub issue #2918 closed as completed)

Previous Symptom: Wrangler build failed with React import errors when using motion package.

Current State: Motion now works correctly with Cloudflare Workers. No workaround needed.

If you encounter build issues: Ensure you're using Motion v12.23.24 or later and Wrangler v3+.

GitHub issue: #2918 (closed as completed Dec 13, 2024)

Issue 7: Fixed Position Layout Animations

Symptom: Layout animations in fixed elements have incorrect positioning.

Solution: Add layoutRoot prop:

  Content

Issue 8: layoutId + AnimatePresence Unmounting

Symptom: Elements with layoutId inside AnimatePresence fail to unmount.

Solution: Wrap in LayoutGroup or avoid mixing exit + layout animations:

import { LayoutGroup } from "motion/react"

  
    {items.map(item => (
      
        {item.content}
      
    ))}
  

Issue 9: Reduced Motion with AnimatePresence (✅ RESOLVED)

Status: ✅ Fixed in January 2023 (GitHub issue #1567 closed via PR #1891)

Previous Symptom: MotionConfig reducedMotion setting didn't affect AnimatePresence animations.

Current State: MotionConfig now correctly applies reducedMotion to AnimatePresence components. The setting works as documented.

Optional Manual Control: If you need custom behavior beyond the built-in support:

const prefersReducedMotion = window.matchMedia("(prefers-reduced-motion: reduce)").matches

GitHub issue: #1567 (closed as completed Jan 13, 2023)

Issue 10: Reorder Component Limitations

Error: Reorder auto-scroll fails, doesn't work with Next.js routing Source: GitHub Issue #3469, #2183, #2101

Why It Happens:

• Page-level scrolling: Reorder auto-scroll only works when Reorder.Group is inside element with overflow: auto/scroll, NOT when document itself is scrollable
• Next.js routing: Incompatible with Next.js routing system, causes random stuck states

Prevention:

// ❌ Wrong - Page-level scrolling (auto-scroll fails)

  
    {/* Auto-scroll doesn't trigger at viewport edges */}
  

// ✅ Correct - Container with overflow

  
    {items.map(item => (
      
        {item.content}
      
    ))}
  

// ✅ Alternative - Use DnD Kit for complex cases
// Motion docs officially recommend DnD Kit for:
// - Multi-row reordering
// - Dragging between columns
// - Page-level scrollable containers
// - Complex drag-and-drop interactions

// Install: pnpm add @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities

See references/nextjs-integration.md for full Next.js troubleshooting guide.

Issue 11: React 19 StrictMode Drag Bug

Error: Drag gestures break when dragging from top to bottom in file trees Source: GitHub Issue #3169

Why It Happens: Only occurs with React 19 + StrictMode enabled + Ant Design components. Dragged element position breaks and appears offset. Does NOT occur in React 18 or React 19 without StrictMode. Only affects top-to-bottom drag (bottom-to-top works fine).

Prevention: Temporarily disable StrictMode for React 19 projects using drag gestures, or use React 18 if StrictMode is critical. Awaiting official fix from Motion team.

Issue 12: Layout Animations in Scaled Containers

Error: Layout animations start from incorrect positions in scaled parent containers Source: GitHub Issue #3356

Why It Happens: Layout animation system uses scaled coordinates as if they were unscaled. Motion's layout animations work in pixels, while parent scale affects visual coordinates. The mismatch causes position calculation errors.

Prevention (Community Workaround):

// Use transformTemplate to correct for parent scale
const scale = 2; // Parent's transform scale value

   {
      const match = /translate3d\((.+)px,\s?(.+)px,\s?(.+)px\)/.exec(generated);
      if (match) {
        const [,

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [fellipeutaka](https://github.com/fellipeutaka)
- **Source:** [fellipeutaka/leon](https://github.com/fellipeutaka/leon)
- **License:** MIT

Install and usage instructions live in the source repository linked above.