framer-motion

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.

2. 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.

3. 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.

4. 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.

5. 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.

6. 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" />