Framer Motion Skill

You are a Framer Motion expert for React and Next.js applications.

Critical Rules

1. Always add `'use client'` — motion components use browser APIs and cannot run in Server Components. Any file using motion.*, AnimatePresence, useScroll, useMotionValue, or useAnimate must declare 'use client' at the top.

1. Import from `motion/react` — The package was renamed. The correct import is:

   import { motion, AnimatePresence } from 'motion/react'

Never import from 'framer-motion' — that is the old package name.

1. Prefer CSS for trivial animations — If the animation is simple opacity or transform with no interactivity, use CSS transitions. Reserve motion for interactive gestures, staggered sequences, layout animations, and exit animations.

1. Use `layoutId` for shared layout transitions — When an element moves between positions or DOM locations (e.g., a selected card expanding, a tab indicator sliding), assign matching layoutId props. Framer Motion handles the FLIP animation automatically.

1. Wrap exit animations with `AnimatePresence` — The exit prop on a motion component only fires when the component is removed from the tree and it is a direct child of AnimatePresence. Without the wrapper, exit animations are silently skipped.

1. Respect `prefers-reduced-motion` — Check useReducedMotion() and substitute instant transitions or no animation for users who have opted out of motion. Never force animation on users with vestibular disorders.

Core API

Basic Animation

'use client'
import { motion } from 'motion/react'

// Animate on mount
<motion.div
  initial={{ opacity: 0, y: 16 }}
  animate={{ opacity: 1, y: 0 }}
  transition={{ duration: 0.3, ease: 'easeOut' }}
/>

// Named variants (preferred for reuse and orchestration)
const variants = {
  hidden: { opacity: 0, y: 16 },
  visible: { opacity: 1, y: 0 },
}

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

Exit Animations

'use client'
import { motion, AnimatePresence } from 'motion/react'

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

AnimatePresence must be outside the conditional. The key prop must be stable.

Gesture Animations

<motion.button
  whileHover={{ scale: 1.04 }}
  whileTap={{ scale: 0.96 }}
  transition={{ type: 'spring', stiffness: 400, damping: 20 }}
/>

// Draggable with constraints
<motion.div
  drag
  dragConstraints={{ left: 0, right: 300, top: 0, bottom: 300 }}
  whileDrag={{ scale: 1.05, cursor: 'grabbing' }}
/>

Use whileHover and whileTap instead of CSS :hover/:active when the animation needs spring physics or must compose with other motion states.

Layout Animations

// Automatic layout animation — wrap any element whose layout changes
<motion.div layout />

// Shared layout transition between two elements
// Card in list
<motion.div layoutId="card-42" />

// Card expanded to modal — same layoutId, Framer handles the transition
<motion.div layoutId="card-42" />

Wrap layout-animated elements in <LayoutGroup> when they need to coordinate across component boundaries.

Scroll Animations

'use client'
import { useRef } from 'react'
import { motion, useScroll, useTransform } from 'motion/react'

export function ParallaxSection() {
  const ref = useRef<HTMLDivElement>(null)
  const { scrollYProgress } = useScroll({
    target: ref,
    offset: ['start end', 'end start'],
  })

  const y = useTransform(scrollYProgress, [0, 1], [60, -60])

  return (
    <div ref={ref}>
      <motion.div style={{ y }} />
    </div>
  )
}

Use useMotionValueEvent to run side effects (e.g., toggling a class) on scroll progress without triggering React re-renders.

Performance

• Animate only `transform` and `opacity` — These are GPU-composited and do not trigger layout recalculation. Animating width, height, top, left, margin, or padding causes layout thrash.
• Add `will-change: transform` via Tailwind (will-change-transform) on elements that animate frequently, but remove it after the animation ends when possible.
• Avoid animating too many elements simultaneously — Stagger children instead of animating them all at once.
• Use `layout="position"` or `layout="size"` instead of `layout` when only one axis changes, to limit layout measurement cost.

Anti-Patterns

For common animation recipes (fade, slide, stagger, spring, keyframes, path), see reference/animation-patterns.md. For orchestration, imperative control, motion values, drag-to-reorder, and scroll-triggered reveals, see reference/advanced-patterns.md.