framer-motion（Framer Motion 工具）

Motion (Framer Motion) — Animation Skill

Production-grade animation patterns for React and Next.js. This skill helps you write correct, performant, accessible animations using the Motion library (v12+).

Imports

Motion rebranded from framer-motion to motion. Both package names work, but the import path matters:

// Client Components (standard React)
import { motion, AnimatePresence } from "motion/react"

// Next.js Server Components — use the client export
import * as motion from "motion/react-client"

// Legacy import (still works with the framer-motion package)
import { motion } from "framer-motion"

If the project already uses framer-motion as a dependency, keep using "framer-motion" imports for consistency. Don't mix import sources.

Core Concepts

motion.* Components

Every HTML/SVG element has a motion counterpart. These accept animation props:

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

Important: motion.* components are client components. In Next.js App Router, either mark the file "use client" or wrap them in a client component.

MotionValues — Animate Without Re-renders

useMotionValue creates values that update without triggering React re-renders. This is the key to 60fps animations:

const x = useMotionValue(0)
const opacity = useTransform(x, [-200, 0, 200], [0, 1, 0])

return <motion.div style={{ x, opacity }} drag="x" />

Rules:

• Use useMotionValue for any value that changes every frame (scroll position, drag position, continuous animation)
• Use useTransform to derive values from other MotionValues (no re-renders)
• Never use useState for frame-by-frame updates — it causes re-renders on every frame

Transitions

Control how animations move between states:

// Spring (default for physical properties like x, y, scale)
transition={{ type: "spring", stiffness: 300, damping: 30 }}

// Tween (default for non-physical properties like opacity, color)
transition={{ type: "tween", duration: 0.3, ease: "easeInOut" }}

// Custom cubic bezier
transition={{ duration: 0.7, ease: [0.16, 1, 0.3, 1] }}

Common Patterns

Scroll-Triggered Fade-In

The most common animation pattern. Use whileInView — do NOT manually use IntersectionObserver:

<motion.div
  initial={{ opacity: 0, y: 24 }}
  whileInView={{ opacity: 1, y: 0 }}
  viewport={{ once: true, amount: 0.1 }}
  transition={{ duration: 0.6, ease: [0.16, 1, 0.3, 1] }}
>
  {children}
</motion.div>

• viewport.once: true — only animate on first entry (standard for marketing pages)
• viewport.amount — how much of the element must be visible (0.1 = 10%)
• viewport.margin — extend the trigger area (e.g., "0px 0px 50px 0px")

Staggered Children

Animate children one after another using variants:

const container = {
  hidden: {},
  show: { transition: { staggerChildren: 0.1 } },
}

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

<motion.ul variants={container} initial="hidden" whileInView="show" viewport={{ once: true }}>
  {items.map((i) => (
    <motion.li key={i} variants={item}>{i}</motion.li>
  ))}
</motion.ul>

Variants propagate — parent state changes flow to children automatically.

Exit Animations with AnimatePresence

Wrap conditionally rendered elements to animate them out before removal:

<AnimatePresence>
  {isOpen && (
    <motion.div
      key="modal"
      initial={{ opacity: 0, scale: 0.95 }}
      animate={{ opacity: 1, scale: 1 }}
      exit={{ opacity: 0, scale: 0.95 }}
      transition={{ duration: 0.2 }}
    />
  )}
</AnimatePresence>

Rules:

• Children must have a unique key
• exit prop defines the exit animation
• Use mode="wait" to finish exit before entering next element
• Use mode="popLayout" for layout-aware transitions

Scroll-Linked Animations

Tie animation directly to scroll position:

const { scrollYProgress } = useScroll()
const opacity = useTransform(scrollYProgress, [0, 0.5], [1, 0])
const scale = useTransform(scrollYProgress, [0, 1], [1, 0.8])

return <motion.div style={{ opacity, scale }} />

For element-specific scroll tracking:

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

Smooth Spring Values

Use useSpring for buttery-smooth transitions of MotionValues:

const scrollY = useMotionValue(0)
const smoothY = useSpring(scrollY, { stiffness: 100, damping: 30 })

Continuous Animation (useAnimationFrame)

For animations that run every frame (gradient shimmer, counting, etc.):

const progress = useMotionValue(0)

useAnimationFrame((time, delta) => {
  const newValue = (time / 1000) % 100
  progress.set(newValue)
})

const backgroundPosition = useTransform(progress, (p) => `${p}% 50%`)

return <motion.span style={{ backgroundPosition }} />

Layout Animations

Animate layout changes automatically:

// Simple layout animation
<motion.div layout />

// Shared layout animation between components
<motion.div layoutId="hero-image" />

When the same layoutId exists in two different components, Motion animates between them (e.g., thumbnail to full-screen).

Gesture Animations

<motion.button
  whileHover={{ scale: 1.05 }}
  whileTap={{ scale: 0.97 }}
  whileFocus={{ outline: "2px solid #5227FF" }}
  transition={{ type: "spring", stiffness: 400, damping: 17 }}
/>

Drag

<motion.div
  drag           // enable both axes
  drag="x"       // constrain to x-axis
  dragConstraints={{ left: -100, right: 100 }}
  dragElastic={0.2}
  onDragEnd={(e, info) => {
    if (info.offset.x > 100) handleSwipeRight()
  }}
/>

Accessibility

useReducedMotion

Always respect the user's motion preferences. This is not optional — it's an accessibility requirement:

import { useReducedMotion } from "framer-motion"

function AnimatedComponent({ children }) {
  const prefersReducedMotion = useReducedMotion()

  if (prefersReducedMotion) {
    return <div>{children}</div>
  }

  return (
    <motion.div
      initial={{ opacity: 0, y: 20 }}
      whileInView={{ opacity: 1, y: 0 }}
    >
      {children}
    </motion.div>
  )
}

Pattern: Check useReducedMotion() and either skip animation entirely or reduce it to opacity-only (no movement).

Performance Rules

1. Never animate width, height, top, left — these trigger layout recalculation. Use transform properties instead (x, y, scale, rotate).
2. Use MotionValues for frame-by-frame updates — useState causes re-renders on every frame. MotionValues update the DOM directly.
3. will-change: transform is added automatically by motion components — don't add it manually.
4. layout animations are expensive — use them intentionally, not on every element.
5. Avoid animating box-shadow — use filter: drop-shadow() or animate opacity of a pseudo-element shadow instead.
6. Prefer opacity and transform — these are GPU-composited and run on a separate thread.
7. Spring transitions are more natural than tween/easing for interactive elements (hover, tap, drag). Reserve tween for scroll-triggered entrances.

Common Mistakes

Recipes

Progress Bar on Scroll

const { scrollYProgress } = useScroll()
return (
  <motion.div
    className="fixed top-0 left-0 right-0 h-1 bg-primary origin-left z-50"
    style={{ scaleX: scrollYProgress }}
  />
)

Animated Counter

const count = useMotionValue(0)
const rounded = useTransform(count, (v) => Math.round(v))

useEffect(() => {
  const controls = animate(count, target, { duration: 2 })
  return controls.stop
}, [target])

return <motion.span>{rounded}</motion.span>

Page Transition (Next.js App Router)

// template.tsx
"use client"
import { motion } from "framer-motion"

export default function Template({ children }) {
  return (
    <motion.div
      initial={{ opacity: 0 }}
      animate={{ opacity: 1 }}
      transition={{ duration: 0.3 }}
    >
      {children}
    </motion.div>
  )
}

Animated Gradient Text (Shimmer Effect)

const progress = useMotionValue(0)

useAnimationFrame((time) => {
  const duration = 8000
  const fullCycle = duration * 2
  const cycleTime = (time % fullCycle)
  if (cycleTime < duration) {
    progress.set((cycleTime / duration) * 100)
  } else {
    progress.set(100 - ((cycleTime - duration) / duration) * 100)
  }
})

const backgroundPosition = useTransform(progress, (p) => `${p}% 50%`)

return (
  <motion.span
    className="bg-clip-text text-transparent"
    style={{
      backgroundImage: "linear-gradient(to right, #5227FF, #a78bfa, #c084fc, #5227FF)",
      backgroundSize: "300% 100%",
      backgroundPosition,
    }}
  >
    {text}
  </motion.span>
)