Motion Framer

Motion & Framer Motion

Overview

Motion (formerly Framer Motion) is a production-ready animation library for React and JavaScript that enables declarative, performant animations with minimal code. It provides motion components that wrap HTML elements with animation superpowers, supports gesture recognition (hover, tap, drag, focus), and includes advanced features like layout animations, exit animations, and spring physics.

When to use this skill:

• Building interactive UI components (buttons, cards, menus)
• Creating micro-interactions and hover effects
• Implementing page transitions and route animations
• Adding scroll-based animations and parallax effects
• Animating layout changes (resizing, reordering, shared element transitions)
• Drag-and-drop interfaces
• Complex animation sequences and state-based animations
• Replacing CSS transitions with more powerful, controllable animations

Technology:

• Motion (v11+) - The modern, smaller library from Framer Motion creators
• Framer Motion - The full-featured predecessor (still widely used)
• React 18+ compatible, also supports Vue
• Supports TypeScript
• Works with Next.js, Vite, Remix, and all modern React frameworks

Core Concepts

1. Motion Components

Convert any HTML/SVG element into an animatable component by prefixing with motion.:

import { motion } from "framer-motion"

// Regular HTML becomes motion component
<motion.div />
<motion.button />
<motion.svg />
<motion.path />

Every motion component accepts animation props like animate, initial, transition, and gesture props like whileHover, whileTap, etc.

2. Animate Prop

The animate prop defines the target animation state. When values change, Motion automatically animates to them:

// Simple animation - x position changes
<motion.div animate={{ x: 100 }} />

// Multiple properties
<motion.div animate={{ x: 100, opacity: 1, scale: 1.2 }} />

// Animates when state changes
const [isOpen, setIsOpen] = useState(false)
<motion.div animate={{ width: isOpen ? 300 : 100 }} />

3. Initial State

Set the initial state before animation using the initial prop:

<motion.div
  initial={{ opacity: 0, y: 50 }}
  animate={{ opacity: 1, y: 0 }}
/>

Set initial={false} to disable initial animations on mount.

4. Transitions

Control how animations move between states using the transition prop:

// Duration-based
<motion.div
  animate={{ x: 100 }}
  transition={{ duration: 0.5, ease: "easeInOut" }}
/>

// Spring physics
<motion.div
  animate={{ scale: 1.2 }}
  transition={{ type: "spring", stiffness: 300, damping: 20 }}
/>

// Different transitions for different properties
<motion.div
  animate={{ x: 100, opacity: 1 }}
  transition={{
    x: { type: "spring", stiffness: 300 },
    opacity: { duration: 0.2 }
  }}
/>

Transition types:

• "tween" (default) - Duration-based with easing
• "spring" - Physics-based spring animation
• "inertia" - Decelerating animation (used in drag)

5. Variants

Organize animation states using named variants for cleaner code and propagation to children:

const variants = {
  hidden: { opacity: 0, y: 20 },
  visible: { opacity: 1, y: 0 },
  exit: { opacity: 0, scale: 0.9 }
}

<motion.div
  variants={variants}
  initial="hidden"
  animate="visible"
  exit="exit"
/>

Variant propagation - Children automatically inherit parent variant states:

const containerVariants = {
  hidden: { opacity: 0 },
  visible: {
    opacity: 1,
    transition: {
      staggerChildren: 0.1  // Stagger child animations
    }
  }
}

const itemVariants = {
  hidden: { x: -20, opacity: 0 },
  visible: { x: 0, opacity: 1 }
}

<motion.ul variants={containerVariants} initial="hidden" animate="visible">
  <motion.li variants={itemVariants} />
  <motion.li variants={itemVariants} />
  <motion.li variants={itemVariants} />
</motion.ul>

Common Patterns

1. Hover Animations

Animate on hover using whileHover prop:

// Simple hover effect
<motion.button
  whileHover={{ scale: 1.1 }}
  transition={{ duration: 0.2 }}
>
  Hover me
</motion.button>

// Multiple properties
<motion.div
  whileHover={{
    scale: 1.05,
    backgroundColor: "#f0f0f0",
    boxShadow: "0px 10px 30px rgba(0, 0, 0, 0.2)"
  }}
>
  Hover card
</motion.div>

// With custom transition
<motion.button
  whileHover={{
    scale: 1.2,
    transition: { duration: 0.1 }  // Transition for gesture start
  }}
  transition={{ duration: 0.5 }}  // Transition for gesture end
>
  Button
</motion.button>

Hover with nested elements:

<motion.div whileHover="hover" variants={cardVariants}>
  <motion.h3 variants={titleVariants}>Title</motion.h3>
  <motion.img variants={imageVariants} />
</motion.div>

2. Tap/Press Animations

Animate on tap/press using whileTap prop:

// Scale down on tap
<motion.button
  whileTap={{ scale: 0.9 }}
>
  Click me
</motion.button>

// Combined hover + tap
<motion.button
  whileHover={{ scale: 1.1 }}
  whileTap={{ scale: 0.95, rotate: 3 }}
>
  Interactive button
</motion.button>

// With variants
const buttonVariants = {
  rest: { scale: 1 },
  hover: { scale: 1.1 },
  pressed: { scale: 0.95 }
}

<motion.button
  variants={buttonVariants}
  initial="rest"
  whileHover="hover"
  whileTap="pressed"
>
  Button
</motion.button>

3. Drag Interactions

Make elements draggable with the drag prop:

// Basic dragging (both axes)
<motion.div drag />

// Constrain to axis
<motion.div drag="x" />  // Only horizontal
<motion.div drag="y" />  // Only vertical

// Drag constraints
<motion.div
  drag
  dragConstraints={{ left: -100, right: 100, top: -100, bottom: 100 }}
/>

// Drag with parent constraints
<motion.div ref={constraintsRef}>
  <motion.div drag dragConstraints={constraintsRef} />
</motion.div>

// Visual feedback while dragging
<motion.div
  drag
  whileDrag={{
    scale: 1.1,
    boxShadow: "0px 10px 20px rgba(0,0,0,0.2)",
    cursor: "grabbing"
  }}
  dragElastic={0.1}  // Elasticity when dragging outside constraints
  dragTransition={{ bounceStiffness: 600, bounceDamping: 20 }}
/>

Drag events:

<motion.div
  drag
  onDragStart={(event, info) => console.log(info.point)}
  onDrag={(event, info) => console.log(info.offset)}
  onDragEnd={(event, info) => console.log(info.velocity)}
/>

4. Exit Animations (AnimatePresence)

Animate components when they're removed from the DOM using AnimatePresence:

import { AnimatePresence } from "framer-motion"

// Basic exit animation
<AnimatePresence>
  {isVisible && (
    <motion.div
      key="modal"
      initial={{ opacity: 0 }}
      animate={{ opacity: 1 }}
      exit={{ opacity: 0 }}
    />
  )}
</AnimatePresence>

Key requirements:

• Component must be direct child of <AnimatePresence>
• Must have a unique key prop
• Use exit prop to define exit animation

List items with exit animations:

<AnimatePresence>
  {items.map(item => (
    <motion.li
      key={item.id}
      initial={{ opacity: 0, x: -50 }}
      animate={{ opacity: 1, x: 0 }}
      exit={{ opacity: 0, x: 50 }}
      layout  // Smooth layout shifts
    >
      {item.name}
    </motion.li>
  ))}
</AnimatePresence>

Staggered exit animations:

const containerVariants = {
  hidden: { opacity: 0 },
  visible: {
    opacity: 1,
    transition: {
      when: "beforeChildren",
      staggerChildren: 0.1
    }
  },
  exit: {
    opacity: 0,
    transition: {
      when: "afterChildren",
      staggerChildren: 0.05,
      staggerDirection: -1  // Reverse order
    }
  }
}

<AnimatePresence>
  {show && (
    <motion.div variants={containerVariants} initial="hidden" animate="visible" exit="exit">
      <motion.div variants={itemVariants} />
      <motion.div variants={itemVariants} />
      <motion.div variants={itemVariants} />
    </motion.div>
  )}
</AnimatePresence>

5. Layout Animations

Automatically animate layout changes (position, size) with the layout prop:

// Animate all layout changes
<motion.div layout />

// Animate only position changes
<motion.div layout="position" />

// Animate only size changes
<motion.div layout="size" />

Grid layout animation:

const [columns, setColumns] = useState(3)

<motion.div className="grid">
  {items.map(item => (
    <motion.div
      key={item.id}
      layout
      transition={{ layout: { duration: 0.3, ease: "easeInOut" } }}
    />
  ))}
</motion.div>

Shared layout animations (layoutId):

Connect two different elements for smooth transitions using layoutId:

// Tab indicator example
<nav>
  {tabs.map(tab => (
    <button key={tab.id} onClick={() => setActive(tab.id)}>
      {tab.label}
      {activeTab === tab.id && (
        <motion.div
          layoutId="underline"
          style={{ position: 'absolute', bottom: 0, left: 0, right: 0, height: 2 }}
        />
      )}
    </button>
  ))}
</nav>

// Modal opening from thumbnail
<motion.img
  src={thumbnail}
  layoutId="product-image"
  onClick={() => setExpanded(true)}
/>

<AnimatePresence>
  {expanded && (
    <motion.div layoutId="product-image">
      <img src={fullsize} />
    </motion.div>
  )}
</AnimatePresence>

6. Scroll-Based Animations

Animate elements when they enter the viewport using whileInView:

<motion.div
  initial={{ opacity: 0, y: 50 }}
  whileInView={{ opacity: 1, y: 0 }}
  viewport={{ once: true, amount: 0.8 }}  // once: trigger once, amount: 80% visible
  transition={{ duration: 0.5 }}
>
  Animates when scrolled into view
</motion.div>

Viewport options:

• once: true - Animation triggers only once
• amount: 0.5 - Percentage of element visible (0-1) or "some" | "all"
• margin: "-100px" - Offset viewport boundaries

Staggered scroll animations:

<motion.ul
  initial="hidden"
  whileInView="visible"
  viewport={{ once: true, amount: 0.3 }}
  variants={{
    visible: {
      opacity: 1,
      transition: { staggerChildren: 0.1 }
    },
    hidden: { opacity: 0 }
  }}
>
  <motion.li variants={itemVariants} />
  <motion.li variants={itemVariants} />
  <motion.li variants={itemVariants} />
</motion.ul>

7. Spring Animations

Use spring physics for natural, bouncy animations:

// Basic spring
<motion.div
  animate={{ scale: 1.2 }}
  transition={{ type: "spring" }}
/>

// Customize spring physics
<motion.div
  animate={{ x: 100 }}
  transition={{
    type: "spring",
    stiffness: 300,  // Higher = faster, snappier (default: 100)
    damping: 20,     // Higher = less bouncy (default: 10)
    mass: 1,         // Higher = more inertia (default: 1)
  }}
/>

// Visual duration (easier spring control)
<motion.div
  animate={{ rotate: 90 }}
  transition={{
    type: "spring",
    visualDuration: 0.5,  // Perceived duration
    bounce: 0.25          // Bounciness (0-1, default: 0.25)
  }}
/>

Spring presets:

• Gentle: stiffness: 100, damping: 20
• Wobbly: stiffness: 200, damping: 10
• Stiff: stiffness: 400, damping: 30
• Slow: stiffness: 50, damping: 20

Gesture Recognition

Motion provides declarative gesture handlers:

Gesture Props

<motion.div
  whileHover={{ scale: 1.1 }}        // Pointer hovers over element
  whileTap={{ scale: 0.9 }}          // Primary pointer presses element
  whileFocus={{ outline: "2px" }}    // Element gains focus
  whileDrag={{ scale: 1.1 }}         // Element is being dragged
  whileInView={{ opacity: 1 }}       // Element is in viewport
/>

Gesture Events

<motion.div
  onHoverStart={(event, info) => {}}
  onHoverEnd={(event, info) => {}}
  onTap={(event, info) => {}}
  onTapStart={(event, info) => {}}
  onTapCancel={(event, info) => {}}
  onDragStart={(event, info) => {}}
  onDrag={(event, info) => {}}
  onDragEnd={(event, info) => {}}
  onViewportEnter={(entry) => {}}
  onViewportLeave={(entry) => {}}
/>

Event info objects contain:

• point: { x, y } - Page coordinates
• offset: { x, y } - Offset from drag start
• velocity: { x, y } - Drag velocity

Hooks

useAnimate

Manually control animations with the useAnimate hook:

import { useAnimate } from "framer-motion"

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

  useEffect(() => {
    // Animate multiple elements
    animate([
      [scope.current, { opacity: 1 }],
      ["li", { x: 0, opacity: 1 }, { delay: stagger(0.1) }],
      [".button", { scale: 1.2 }]
    ])
  }, [])

  return (
    <div ref={scope}>
      <ul>
        <li>Item 1</li>
        <li>Item 2</li>
      </ul>
      <button className="button">Click</button>
    </div>
  )
}

Animation controls:

const controls = animate(element, { x: 100 })
controls.play()
controls.pause()
controls.stop()
controls.speed = 0.5
controls.time = 0  // Seek to start

useSpring

Create spring-animated motion values:

import { useSpring } from "framer-motion"

function Component() {
  const x = useSpring(0, { stiffness: 300, damping: 20 })

  return (
    <motion.div style={{ x }}>
      <button onClick={() => x.set(100)}>Move</button>
    </motion.div>
  )
}

useInView

Detect when an element is in viewport:

import { useInView } from "framer-motion"

function Component() {
  const ref = useRef(null)
  const isInView = useInView(ref, { once: true, amount: 0.5 })

  return (
    <div ref={ref}>
      {isInView ? "In view!" : "Not in view"}
    </div>
  )
}

Integration Patterns

With GSAP

Combine Motion for React state-based animations and GSAP for complex timelines:

import { motion } from "framer-motion"
import gsap from "gsap"

function Component() {
  const boxRef = useRef()

  const handleClick = () => {
    // Use GSAP for complex timeline
    const tl = gsap.timeline()
    tl.to(boxRef.current, { rotation: 360, duration: 1 })
      .to(boxRef.current, { scale: 1.5, duration: 0.5 })
  }

  return (
    // Use Motion for hover/tap/layout animations
    <motion.div
      ref={boxRef}
      whileHover={{ scale: 1.1 }}
      onClick={handleClick}
    />
  )
}

With React Three Fiber

Animate 3D objects using Motion values:

import { motion } from "framer-motion"
import { useFrame } from "@react-three/fiber"

function Box() {
  const x = useMotionValue(0)

  useFrame(() => {
    // Sync Motion value with Three.js position
    meshRef.current.position.x = x.get()
  })

  return (
    <>
      <mesh ref={meshRef}>
        <boxGeometry />
        <meshStandardMaterial />
      </mesh>
      <motion.div
        style={{ x }}
        drag="x"
        dragConstraints={{ left: -5, right: 5 }}
      />
    </>
  )
}

With Form Libraries

Animate form validation states:

import { motion, AnimatePresence } from "framer-motion"

function FormField({ error }) {
  return (
    <div>
      <motion.input
        animate={{
          borderColor: error ? "#ff0000" : "#cccccc",
          x: error ? [0, -10, 10, -10, 10, 0] : 0  // Shake animation
        }}
        transition={{ duration: 0.4 }}
      />
      <AnimatePresence>
        {error && (
          <motion.p
            initial={{ opacity: 0, y: -10 }}
            animate={{ opacity: 1, y: 0 }}
            exit={{ opacity: 0, y: -10 }}
            style={{ color: "#ff0000" }}
          >
            {error}
          </motion.p>
        )}
      </AnimatePresence>
    </div>
  )
}

Performance Optimization

1. Use Transform Properties

Transform properties (x, y, scale, rotate) are hardware-accelerated:

// ✅ Good - Hardware accelerated
<motion.div animate={{ x: 100, scale: 1.2 }} />

// ❌ Avoid - Triggers layout/paint
<motion.div animate={{ left: 100, width: 200 }} />

2. Individual Transform Properties

Motion supports individual transform properties for cleaner code:

// Individual properties (Motion feature)
<motion.div style={{ x: 100, rotate: 45, scale: 1.2 }} />

// Traditional (also supported)
<motion.div style={{ transform: "translateX(100px) rotate(45deg) scale(1.2)" }} />

3. Reduce Motion for Accessibility

Respect user preferences for reduced motion:

import { useReducedMotion } from "framer-motion"

function Component() {
  const shouldReduceMotion = useReducedMotion()

  return (
    <motion.div
      animate={{ x: 100 }}
      transition={shouldReduceMotion ? { duration: 0 } : { duration: 0.5 }}
    />
  )
}

4. Layout Animations Performance

Layout animations can be expensive. Optimize with:

// Specify what to animate
<motion.div layout="position" />  // Only position, not size

// Optimize transition
<motion.div
  layout
  transition={{
    layout: { duration: 0.3, ease: "easeOut" }
  }}
/>

5. Use layoutId Sparingly

layoutId creates shared layout animations but tracks elements globally. Use only when needed.

Common Pitfalls

1. Forgetting AnimatePresence for Exit Animations

Problem: Exit animations don't work

// ❌ Wrong - No AnimatePresence
{show && <motion.div exit={{ opacity: 0 }} />}

// ✅ Correct - Wrapped in AnimatePresence
<AnimatePresence>
  {show && <motion.div exit={{ opacity: 0 }} />}
</AnimatePresence>

2. Missing key Prop in Lists

Problem: AnimatePresence can't track elements

// ❌ Wrong - No key
<AnimatePresence>
  {items.map(item => <motion.div exit={{ opacity: 0 }} />)}
</AnimatePresence>

// ✅ Correct - Unique keys
<AnimatePresence>
  {items.map(item => (
    <motion.div key={item.id} exit={{ opacity: 0 }} />
  ))}
</AnimatePresence>

3. Animating Non-Transform Properties

Problem: Janky animations, poor performance

// ❌ Avoid - Not hardware accelerated
<motion.div animate={{ top: 100, left: 50, width: 200 }} />

// ✅ Better - Use transforms
<motion.div animate={{ x: 50, y: 100, scaleX: 2 }} />

4. Overusing Layout Animations

Problem: Performance issues with many layout-animated elements

// ❌ Too many layout animations
{items.map(item => <motion.div layout>{item}</motion.div>)}

// ✅ Use layout only where needed, optimize others
{items.map(item => (
  <motion.div
    key={item.id}
    animate={{ opacity: 1 }}  // Cheaper animation
    exit={{ opacity: 0 }}
  />
))}

5. Not Using Variants for Complex Animations

Problem: Duplicated animation code, no child orchestration

// ❌ Repetitive
<motion.div initial={{ opacity: 0 }} animate={{ opacity: 1 }} exit={{ opacity: 0 }} />
<motion.div initial={{ opacity: 0 }} animate={{ opacity: 1 }} exit={{ opacity: 0 }} />

// ✅ Use variants
const variants = {
  hidden: { opacity: 0 },
  visible: { opacity: 1 }
}

<motion.div variants={variants} initial="hidden" animate="visible" />
<motion.div variants={variants} initial="hidden" animate="visible" />

6. Incorrect Transition Timing

Problem: Transitions don't apply to specific gestures

// ❌ Wrong - General transition won't apply to whileHover
<motion.div
  whileHover={{ scale: 1.2 }}
  transition={{ duration: 1 }}  // This applies to animate prop, not whileHover
/>

// ✅ Correct - Transition in whileHover or separate gesture transition
<motion.div
  whileHover={{
    scale: 1.2,
    transition: { duration: 0.2 }  // Applies to hover start
  }}
  transition={{ duration: 0.5 }}  // Applies to hover end
/>

Resources

Official Documentation

• Motion Docs - Official Motion documentation
• Framer Motion Docs - Framer Motion (legacy)
• Motion GitHub - Source code & examples

Bundled Resources

This skill includes:

references/

• api_reference.md - Complete Motion API reference
• variants_patterns.md - Variant patterns and orchestration
• gesture_guide.md - Comprehensive gesture handling guide

scripts/

• animation_generator.py - Generate Motion component boilerplate
• variant_builder.py - Interactive variant configuration tool

assets/

• starter_motion/ - Complete Motion + Vite starter template
• examples/ - Real-world Motion component patterns

Community Resources

• Motion Dev Discord - Official community
• Framer Motion Examples - Interactive examples
• Motion Recipes - Common patterns
• CodeSandbox Templates - Live demos

Motion Starter Template

A minimal, production-ready starter template for building animated React applications with Framer Motion.

Features

• ⚡️ Vite - Fast build tool and dev server
• ⚛️ React 18 - Latest React with concurrent features
• 🎨 Framer Motion - Production-ready animation library
• 🎮 Interactive Components - Hover, tap, and drag interactions
• 📤 Exit Animations - AnimatePresence examples
• 🔄 Layout Animations - Smooth layout transitions
• 📜 Stagger Effects - Coordinated child animations

Quick Start

Installation

npm install
# or
yarn
# or
pnpm install

Development

npm run dev

Opens at http://localhost:3000

Build

npm run build

Preview Production Build

npm run preview

Project Structure

starter_motion/
├── index.html           # Entry HTML
├── package.json         # Dependencies
├── vite.config.js       # Vite configuration
└── src/
    ├── main.jsx         # React root
    ├── App.jsx          # Main App with examples
    ├── App.css          # Styles
    └── components/
        ├── HoverCard.jsx       # Hover animation example
        ├── DraggableBox.jsx    # Drag interaction example
        └── StaggerList.jsx     # Staggered animation example

Included Examples

1. Hover Animations (HoverCard)

Demonstrates whileHover for interactive cards:

• Scale on hover
• Shadow effects
• Smooth transitions
• Combined with whileTap

2. Drag Interactions (DraggableBox)

Shows drag functionality:

• Drag constraints
• Visual feedback (whileDrag)
• Drag events (onDragStart, onDragEnd)
• Elastic boundaries

3. Staggered Animations (StaggerList)

Illustrates variant propagation:

• Container/item variant pattern
• staggerChildren for sequential animations
• delayChildren for initial delay
• Combined with hover effects

4. Exit Animations (Modal)

Demonstrates AnimatePresence:

• Exit animations with exit prop
• Modal backdrop fade
• Modal enter/exit with spring physics
• Proper cleanup

Common Patterns

Basic Animation

<motion.div
  initial={{ opacity: 0, y: 20 }}
  animate={{ opacity: 1, y: 0 }}
  transition={{ duration: 0.5 }}
>
  Content
</motion.div>

Hover Effect

<motion.button
  whileHover={{ scale: 1.05 }}
  whileTap={{ scale: 0.95 }}
>
  Click me
</motion.button>

Drag Interaction

<motion.div
  drag
  dragConstraints={{ left: -100, right: 100, top: -100, bottom: 100 }}
  whileDrag={{ scale: 1.1 }}
>
  Drag me
</motion.div>

Exit Animation

<AnimatePresence>
  {show && (
    <motion.div
      initial={{ opacity: 0 }}
      animate={{ opacity: 1 }}
      exit={{ opacity: 0 }}
    />
  )}
</AnimatePresence>

Variants with Stagger

const container = {
  hidden: { opacity: 0 },
  visible: {
    opacity: 1,
    transition: { staggerChildren: 0.1 }
  }
}

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

<motion.ul variants={container} initial="hidden" animate="visible">
  <motion.li variants={item}>Item 1</motion.li>
  <motion.li variants={item}>Item 2</motion.li>
</motion.ul>

Customization

Add New Components

Create new components in src/components/:

// src/components/MyComponent.jsx
import { motion } from 'framer-motion'

export default function MyComponent() {
  return (
    <motion.div
      whileHover={{ scale: 1.1 }}
      whileTap={{ scale: 0.9 }}
    >
      My Content
    </motion.div>
  )
}

Import in App.jsx:

import MyComponent from './components/MyComponent'

// In App component:
<MyComponent />

Change Transition Physics

// Duration-based
<motion.div
  animate={{ x: 100 }}
  transition={{ duration: 0.5, ease: "easeInOut" }}
/>

// Spring-based (natural, bouncy)
<motion.div
  animate={{ x: 100 }}
  transition={{ type: "spring", stiffness: 300, damping: 20 }}
/>

Add Scroll Animations

<motion.div
  initial={{ opacity: 0, y: 50 }}
  whileInView={{ opacity: 1, y: 0 }}
  viewport={{ once: true, amount: 0.3 }}
  transition={{ duration: 0.5 }}
>
  Scroll to reveal
</motion.div>

Layout Animations

<motion.div layout>
  {/* Content that changes size/position */}
</motion.div>

Shared Element Transitions

// Tab indicator
{tabs.map(tab => (
  <div key={tab.id}>
    {tab.label}
    {activeTab === tab.id && (
      <motion.div layoutId="underline" />
    )}
  </div>
))}

Performance Tips

1. Use transform properties - Animate x, y, scale, rotate (hardware accelerated) 2. Avoid layout properties - Don't animate width, height, top, left 3. Reduce motion - Respect accessibility preferences:

   import { useReducedMotion } from "framer-motion"

   const shouldReduceMotion = useReducedMotion()

4. Use `will-change` CSS - For complex animations 5. Optimize variants - Reuse variant objects 6. Lazy load heavy components - Use React.lazy() for code splitting

TypeScript Support

To add TypeScript:

npm install -D typescript @types/react @types/react-dom

Rename files to .tsx:

mv src/main.jsx src/main.tsx
mv src/App.jsx src/App.tsx

Add tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

Resources

• Framer Motion Docs - Official documentation
• Motion Dev - New Motion library docs
• Examples - Interactive examples
• API Reference - Complete API

Troubleshooting

Animations Not Working

• Ensure component is wrapped in <motion.*> not regular HTML
• Check that initial and animate props are set
• Verify transition configuration

Exit Animations Not Working

• Wrap component in <AnimatePresence>
• Ensure component has unique key prop
• Add exit prop to motion component

Performance Issues

• Use transform properties (x, y, scale, rotate)
• Avoid animating layout properties
• Reduce number of animated elements
• Use layout="position" instead of layout={true} when possible

Drag Not Working

• Check dragConstraints are set properly
• Ensure parent has defined dimensions
• Verify drag prop is set to true or "x"/"y"

License

MIT - Use freely for personal and commercial projects.

Motion & Framer Motion - Complete API Reference

Comprehensive API documentation for Motion (v11+) and Framer Motion animation libraries.

Table of Contents

1. Motion Component Props 2. Animation Props 3. Gesture Props 4. Layout Props 5. Transition Options 6. Variants 7. Hooks 8. AnimatePresence 9. Utilities

---

Motion Component Props

All motion components (motion.div, motion.button, etc.) accept these props:

Core Animation Props

interface MotionProps {
  // Animation state
  animate?: AnimationControls | TargetAndTransition | VariantLabels
  initial?: boolean | Target | VariantLabels
  exit?: TargetAndTransition | VariantLabels

  // Transition
  transition?: Transition

  // Variants
  variants?: Variants

  // Style
  style?: MotionStyle

  // Layout
  layout?: boolean | "position" | "size"
  layoutId?: string
  layoutDependency?: any
  layoutScroll?: boolean

  // Gestures
  whileHover?: VariantLabels | TargetAndTransition
  whileTap?: VariantLabels | TargetAndTransition
  whileFocus?: VariantLabels | TargetAndTransition
  whileDrag?: VariantLabels | TargetAndTransition
  whileInView?: VariantLabels | TargetAndTransition

  // Drag
  drag?: boolean | "x" | "y"
  dragConstraints?: Constraints | RefObject<Element>
  dragElastic?: DragElastic
  dragMomentum?: boolean
  dragTransition?: InertiaOptions
  dragPropagation?: boolean
  dragSnapToOrigin?: boolean

  // Viewport
  viewport?: ViewportOptions

  // Events
  onUpdate?: (latest: Target) => void
  onAnimationStart?: (definition: AnimationDefinition) => void
  onAnimationComplete?: (definition: AnimationDefinition) => void

  // Hover events
  onHoverStart?: (event: MouseEvent, info: EventInfo) => void
  onHoverEnd?: (event: MouseEvent, info: EventInfo) => void

  // Tap events
  onTap?: (event: MouseEvent | TouchEvent | PointerEvent, info: TapInfo) => void
  onTapStart?: (event: MouseEvent | TouchEvent | PointerEvent, info: TapInfo) => void
  onTapCancel?: (event: MouseEvent | TouchEvent | PointerEvent, info: TapInfo) => void

  // Focus events
  onFocus?: (event: FocusEvent) => void
  onBlur?: (event: FocusEvent) => void

  // Drag events
  onDragStart?: (event: MouseEvent | TouchEvent | PointerEvent, info: PanInfo) => void
  onDrag?: (event: MouseEvent | TouchEvent | PointerEvent, info: PanInfo) => void
  onDragEnd?: (event: MouseEvent | TouchEvent | PointerEvent, info: PanInfo) => void

  // Viewport events
  onViewportEnter?: (entry: IntersectionObserverEntry | null) => void
  onViewportLeave?: (entry: IntersectionObserverEntry | null) => void

  // Pan events
  onPan?: (event: MouseEvent | TouchEvent | PointerEvent, info: PanInfo) => void
  onPanStart?: (event: MouseEvent | TouchEvent | PointerEvent, info: PanInfo) => void
  onPanEnd?: (event: MouseEvent | TouchEvent | PointerEvent, info: PanInfo) => void
}

---

Animation Props

animate

Defines the target animation state. Accepts object, variant label, or animation controls.

// As object
<motion.div animate={{ x: 100, opacity: 1 }} />

// As variant label
<motion.div animate="visible" />

// As array of variant labels (applied in order)
<motion.div animate={["visible", "active"]} />

// Dynamic based on state
<motion.div animate={isOpen ? "open" : "closed"} />

Type:

animate?: AnimationControls | TargetAndTransition | VariantLabels

initial

Sets the initial state before animation. Set to false to disable initial animation.

// As object
<motion.div initial={{ opacity: 0, y: 50 }} />

// As variant label
<motion.div initial="hidden" />

// Disable initial animation
<motion.div initial={false} />

Type:

initial?: boolean | Target | VariantLabels

exit

Defines animation when component is removed from DOM. Requires AnimatePresence.

<AnimatePresence>
  {show && (
    <motion.div
      exit={{ opacity: 0, scale: 0.9 }}
    />
  )}
</AnimatePresence>

Type:

exit?: TargetAndTransition | VariantLabels

style

Motion-specific style prop that supports individual transform properties.

<motion.div
  style={{
    x: 100,           // translateX
    y: 50,            // translateY
    scale: 1.2,       // scale
    rotate: 45,       // rotate in degrees
    rotateX: 90,      // 3D rotation
    opacity: 0.5,
    backgroundColor: "#ff0000"
  }}
/>

Transform properties:

• x, y, z - Translation (px)
• scale, scaleX, scaleY - Scale (unitless)
• rotate, rotateX, rotateY, rotateZ - Rotation (deg)
• skew, skewX, skewY - Skew (deg)
• originX, originY, originZ - Transform origin (0-1 or px)
• perspective - 3D perspective (px)

---

Gesture Props

whileHover

Animation applied while element is hovered.

<motion.button
  whileHover={{ scale: 1.1 }}
  // Or with custom transition
  whileHover={{
    scale: 1.2,
    transition: { duration: 0.1 }
  }}
/>

Type:

whileHover?: VariantLabels | TargetAndTransition

whileTap

Animation applied while element is pressed.

<motion.button
  whileTap={{ scale: 0.9, rotate: 3 }}
/>

Type:

whileTap?: VariantLabels | TargetAndTransition

whileFocus

Animation applied while element has focus.

<motion.input
  whileFocus={{ borderColor: "#0066ff", scale: 1.02 }}
/>

Type:

whileFocus?: VariantLabels | TargetAndTransition

whileDrag

Animation applied while element is being dragged.

<motion.div
  drag
  whileDrag={{ scale: 1.1, cursor: "grabbing" }}
/>

Type:

whileDrag?: VariantLabels | TargetAndTransition

whileInView

Animation applied while element is in viewport.

<motion.div
  initial={{ opacity: 0 }}
  whileInView={{ opacity: 1 }}
  viewport={{ once: true, amount: 0.5 }}
/>

Type:

whileInView?: VariantLabels | TargetAndTransition

---

Layout Props

layout

Enables automatic layout animations for position/size changes.

// Animate all layout changes
<motion.div layout />

// Animate only position
<motion.div layout="position" />

// Animate only size
<motion.div layout="size" />

Type:

layout?: boolean | "position" | "size"

layoutId

Creates shared layout animations between different components.

// Animated tab indicator
{tabs.map(tab => (
  <div key={tab.id}>
    {tab.label}
    {activeTab === tab.id && (
      <motion.div layoutId="underline" />
    )}
  </div>
))}

Type:

layoutId?: string

layoutDependency

Forces layout animation when this value changes.

<motion.div
  layout
  layoutDependency={sortOrder}
/>

Type:

layoutDependency?: any

---

Transition Options

Transition Interface

interface Transition {
  // Duration-based (tween)
  duration?: number
  ease?: Easing | Easing[]
  times?: number[]

  // Spring-based
  type?: "tween" | "spring" | "inertia"
  stiffness?: number
  damping?: number
  mass?: number
  velocity?: number
  restSpeed?: number
  restDelta?: number

  // Visual spring (easier configuration)
  visualDuration?: number
  bounce?: number

  // Timing
  delay?: number
  delayChildren?: number
  staggerChildren?: number
  staggerDirection?: 1 | -1

  // Orchestration
  when?: "beforeChildren" | "afterChildren" | false
  repeat?: number
  repeatType?: "loop" | "reverse" | "mirror"
  repeatDelay?: number

  // Per-property transitions
  [key: string]: any
}

Tween Transitions (Duration-based)

<motion.div
  animate={{ x: 100 }}
  transition={{
    duration: 0.5,
    ease: "easeInOut",
    times: [0, 0.5, 1],  // Keyframe times
    delay: 0.2
  }}
/>

Easing options:

• "linear"
• "easeIn", "easeOut", "easeInOut"
• "circIn", "circOut", "circInOut"
• "backIn", "backOut", "backInOut"
• "anticipate"
• Custom array: [0.42, 0, 0.58, 1] (cubic-bezier)

Spring Transitions (Physics-based)

<motion.div
  animate={{ x: 100 }}
  transition={{
    type: "spring",
    stiffness: 300,   // Higher = faster (default: 100)
    damping: 20,      // Higher = less bouncy (default: 10)
    mass: 1,          // Higher = more inertia (default: 1)
    velocity: 50      // Initial velocity
  }}
/>

Visual spring (simplified):

<motion.div
  animate={{ rotate: 90 }}
  transition={{
    type: "spring",
    visualDuration: 0.5,  // Perceived duration
    bounce: 0.25          // Bounciness (0-1)
  }}
/>

Inertia Transitions (Decelerating)

Used automatically in drag. Can be customized:

<motion.div
  drag
  dragTransition={{
    bounceStiffness: 600,
    bounceDamping: 20,
    power: 0.3,
    timeConstant: 200,
    min: 0,
    max: 100
  }}
/>

Orchestration

Staggering children:

const containerVariants = {
  visible: {
    transition: {
      staggerChildren: 0.1,        // Delay between each child
      delayChildren: 0.2,          // Delay before first child
      staggerDirection: 1,         // 1 = forward, -1 = reverse
      when: "beforeChildren"       // Animate parent before/after children
    }
  }
}

Per-property transitions:

<motion.div
  animate={{ x: 100, opacity: 1 }}
  transition={{
    x: { type: "spring", stiffness: 300 },
    opacity: { duration: 0.2 },
    default: { ease: "linear" }
  }}
/>

Repeating animations:

<motion.div
  animate={{ rotate: 360 }}
  transition={{
    repeat: Infinity,
    repeatType: "loop",     // "loop" | "reverse" | "mirror"
    repeatDelay: 1,
    duration: 2
  }}
/>

---

Variants

Variants are predefined animation states that can be applied to components and their children.

Variant Definition

type Variants = {
  [key: string]: TargetAndTransition
}

// Example
const variants: Variants = {
  hidden: {
    opacity: 0,
    y: 20,
    transition: { duration: 0.3 }
  },
  visible: {
    opacity: 1,
    y: 0,
    transition: { duration: 0.5, delay: 0.1 }
  }
}

Variant Propagation

Children inherit parent variant labels automatically:

const container = {
  hidden: { opacity: 0 },
  visible: {
    opacity: 1,
    transition: {
      staggerChildren: 0.1
    }
  }
}

const item = {
  hidden: { x: -20, opacity: 0 },
  visible: { x: 0, opacity: 1 }
}

<motion.ul variants={container} initial="hidden" animate="visible">
  <motion.li variants={item} />
  <motion.li variants={item} />
  <motion.li variants={item} />
</motion.ul>

Dynamic Variants

Variants can be functions that receive custom data:

const variants = {
  visible: (i: number) => ({
    opacity: 1,
    transition: {
      delay: i * 0.1
    }
  })
}

{items.map((item, i) => (
  <motion.div
    key={item.id}
    custom={i}
    variants={variants}
    animate="visible"
  />
))}

---

Hooks

useAnimate

Manually control animations with imperative API.

import { useAnimate, stagger } from "framer-motion"

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

  // Animate single element
  animate(scope.current, { x: 100 })

  // Animate with selector
  animate("li", { opacity: 1 })

  // Sequence of animations
  animate([
    [scope.current, { opacity: 1 }],
    ["li", { x: 0 }, { delay: stagger(0.1) }],
    [".button", { scale: 1.2 }]
  ])

  return <div ref={scope}>...</div>
}

Returns: [scope: RefObject, animate: AnimateFunction]

AnimationControls methods:

const controls = animate(element, { x: 100 })
controls.play()
controls.pause()
controls.stop()
controls.cancel()
controls.speed = 0.5
controls.time = 0
controls.then(() => console.log("Complete"))

useMotionValue

Create a motion value that can be read, set, and animated.

import { useMotionValue } from "framer-motion"

const x = useMotionValue(0)

// Get value
const currentX = x.get()

// Set value
x.set(100)

// Listen to changes
x.on("change", (latest) => console.log(latest))
x.on("animationStart", () => {})
x.on("animationComplete", () => {})

// Use in component
<motion.div style={{ x }} />

useTransform

Transform one motion value into another.

import { useMotionValue, useTransform } from "framer-motion"

const x = useMotionValue(0)

// Linear interpolation
const opacity = useTransform(x, [0, 100], [1, 0])

// Custom transform function
const backgroundColor = useTransform(
  x,
  [0, 100],
  ["#ff0000", "#0000ff"]
)

<motion.div style={{ x, opacity, backgroundColor }} />

useSpring

Create spring-animated motion value.

import { useSpring, useMotionValue } from "framer-motion"

const x = useMotionValue(0)
const springX = useSpring(x, { stiffness: 300, damping: 20 })

<motion.div style={{ x: springX }} />

Options:

interface SpringOptions {
  stiffness?: number
  damping?: number
  mass?: number
  velocity?: number
  restSpeed?: number
  restDelta?: number
}

useScroll

Track scroll position and velocity.

import { useScroll } from "framer-motion"

const { scrollX, scrollY, scrollXProgress, scrollYProgress } = useScroll()

// With element ref
const ref = useRef(null)
const { scrollYProgress } = useScroll({
  target: ref,
  offset: ["start end", "end start"]
})

<motion.div style={{ scaleX: scrollYProgress }} />

Options:

interface ScrollOptions {
  target?: RefObject<Element>
  offset?: ["start" | "end" | string, "start" | "end" | string]
  container?: RefObject<Element>
  layoutEffect?: boolean
}

useInView

Detect when element is in viewport.

import { useInView } from "framer-motion"

const ref = useRef(null)
const isInView = useInView(ref, {
  once: true,
  amount: 0.5,
  margin: "-100px"
})

<div ref={ref}>
  {isInView ? "Visible!" : "Not visible"}
</div>

Options:

interface InViewOptions {
  once?: boolean
  amount?: "some" | "all" | number
  margin?: string
  root?: RefObject<Element>
}

useReducedMotion

Detect user's motion preferences.

import { useReducedMotion } from "framer-motion"

const shouldReduceMotion = useReducedMotion()

<motion.div
  animate={{ x: 100 }}
  transition={shouldReduceMotion ? { duration: 0 } : { duration: 0.5 }}
/>

useAnimationControls

Create animation controls for imperative animations.

import { useAnimationControls } from "framer-motion"

const controls = useAnimationControls()

controls.start({ x: 100 })
controls.stop()
controls.set({ x: 0 })

<motion.div animate={controls} />

usePresence

Detect if component is present (for custom exit animations).

import { usePresence } from "framer-motion"

const [isPresent, safeToRemove] = usePresence()

useEffect(() => {
  if (!isPresent) {
    // Perform exit animation
    animate(ref.current, { opacity: 0 }).then(safeToRemove)
  }
}, [isPresent])

---

AnimatePresence

Enables exit animations for removed components.

Basic Usage

import { AnimatePresence } from "framer-motion"

<AnimatePresence>
  {show && (
    <motion.div
      key="modal"
      initial={{ opacity: 0 }}
      animate={{ opacity: 1 }}
      exit={{ opacity: 0 }}
    />
  )}
</AnimatePresence>

Props

interface AnimatePresenceProps {
  // Initial animation on first mount
  initial?: boolean

  // Custom data for exit animations
  custom?: any

  // Wait for all exiting animations to complete
  mode?: "wait" | "sync" | "popLayout"

  // Callback when all exit animations complete
  onExitComplete?: () => void

  // Propagate exit to nested AnimatePresence
  propagate?: boolean
}

Mode Options

"sync" (default) - Exit and enter animations happen simultaneously:

<AnimatePresence mode="sync">
  <Component key={page} />
</AnimatePresence>

"wait" - Wait for exit animation before starting enter animation:

<AnimatePresence mode="wait">
  <Component key={page} />
</AnimatePresence>

"popLayout" - Exit components render in a separate layer:

<AnimatePresence mode="popLayout">
  {items.map(item => (
    <motion.div key={item.id} layout />
  ))}
</AnimatePresence>

Custom Data

Pass data to exiting components that can't receive new props:

<AnimatePresence custom={direction}>
  <motion.div
    key={page}
    variants={variants}
    custom={direction}
    exit="exit"
  />
</AnimatePresence>

const variants = {
  exit: (direction) => ({
    x: direction > 0 ? 300 : -300
  })
}

---

Utilities

stagger

Create staggered delays for child animations.

import { stagger } from "framer-motion"

animate("li", { opacity: 1 }, { delay: stagger(0.1) })

// With options
stagger(0.1, {
  startDelay: 0.2,
  from: "first" | "last" | "center" | number,
  ease: "easeInOut"
})

animate (standalone)

Animate any element imperatively.

import { animate } from "framer-motion"

// Single element
animate(element, { x: 100 }, { duration: 0.5 })

// Selector
animate(".box", { opacity: 1 })

// Returns controls
const controls = animate(element, { x: 100 })
controls.pause()

transform

Transform values without motion values.

import { transform } from "framer-motion"

const output = transform(input, [0, 100], [0, 1])

mix

Mix two values.

import { mix } from "framer-motion"

const output = mix(0, 100, 0.5) // 50

clamp

Clamp value between min and max.

import { clamp } from "framer-motion"

const output = clamp(0, 100, 150) // 100

---

Event Info Types

PanInfo (Drag events)

interface PanInfo {
  point: Point         // Page coordinates
  delta: Point         // Change since last event
  offset: Point        // Offset from gesture start
  velocity: Point      // Current velocity
}

TapInfo

interface TapInfo {
  point: Point         // Page coordinates
}

Point

interface Point {
  x: number
  y: number
}

---

TypeScript Support

Import Types

import type {
  TargetAndTransition,
  Transition,
  Variants,
  MotionProps,
  AnimationControls,
  PanInfo,
  TapInfo
} from "framer-motion"

Custom Component with Motion

import { motion, HTMLMotionProps } from "framer-motion"

interface Props extends HTMLMotionProps<"div"> {
  customProp: string
}

const CustomComponent = ({ customProp, ...props }: Props) => {
  return <motion.div {...props}>{customProp}</motion.div>
}

---

Performance Tips

1. Use transform properties (x, y, scale, rotate) - hardware accelerated 2. Avoid animating width, height, top, left, margin, padding 3. Use `layout` sparingly - computationally expensive 4. Use `will-change` CSS for complex animations 5. Use `layoutId` only when needed - tracks elements globally 6. Reduce motion values - each creates subscription overhead 7. Use `useReducedMotion` - respect accessibility preferences

---

Common Patterns Quick Reference

// Hover effect
<motion.div whileHover={{ scale: 1.1 }} />

// Tap feedback
<motion.button whileTap={{ scale: 0.95 }} />

// Drag
<motion.div drag dragConstraints={{ left: 0, right: 300 }} />

// Fade in on mount
<motion.div initial={{ opacity: 0 }} animate={{ opacity: 1 }} />

// Exit animation
<AnimatePresence>
  {show && <motion.div exit={{ opacity: 0 }} />}
</AnimatePresence>

// Layout animation
<motion.div layout />

// Shared layout animation
<motion.div layoutId="shared-element" />

// Scroll-triggered
<motion.div whileInView={{ opacity: 1 }} viewport={{ once: true }} />

// Stagger children
<motion.div variants={container}>
  <motion.div variants={item} />
  <motion.div variants={item} />
</motion.div>

// Spring animation
<motion.div
  animate={{ x: 100 }}
  transition={{ type: "spring", stiffness: 300 }}
/>

---

For more detailed examples and use cases, see the main SKILL.md and examples in the assets directory.