framer-motion
Best practices for Framer Motion / Motion (motion for React) animations — variants, AnimatePresence, layout animations, gestures, performance (transform/opacity, LazyMotion), reduced-motion accessibil
SKILL.mdskills/03-product-engineering/framer-motion/SKILL.md
GitHubFramer Motion / Motion (React)
Animation library for React. Package note: Framer Motion was rebranded to Motion. New projects: npm i motion, import from motion/react. Existing projects on framer-motion (v11/v12): import from framer-motion — same API. Use whichever the project already has; don't mix both.
import { motion, AnimatePresence } from 'motion/react' // or 'framer-motion'
Core patterns
Animate with motion.* + variants (named states keep markup clean and enable orchestration):
const list = { show: { transition: { staggerChildren: 0.06 } } }
const item = { hidden: { opacity: 0, y: 8 }, show: { opacity: 1, y: 0 } }
<motion.ul variants={list} initial="hidden" animate="show">
{items.map((i) => <motion.li key={i.id} variants={item}>{i.label}</motion.li>)}
</motion.ul>
Exit animations need AnimatePresence + a stable key; the exiting element must be a direct child:
<AnimatePresence mode="wait">
{open && <motion.div key="panel" initial={{ opacity: 0 }} animate={{ opacity: 1 }} exit={{ opacity: 0 }} />}
</AnimatePresence>
Scroll-triggered: whileInView={{ opacity: 1 }} viewport={{ once: true, margin: '-10%' }}.
Gestures: whileHover, whileTap, whileFocus, drag.
Shared/layout: add layout for auto-animated layout changes; layoutId="x" for shared-element morphs between components. Use sparingly — layout animations are the most expensive.
Accessibility — respect reduced motion (required)
import { useReducedMotion } from 'motion/react'
const reduce = useReducedMotion()
const variants = reduce ? { hidden: { opacity: 0 }, show: { opacity: 1 } } : fullVariants
Or wrap with <MotionConfig reducedMotion="user">. Never ship motion that ignores prefers-reduced-motion. Keep motion subtle (small distances, short durations, spring or ease-out) — no gratuitous bounce.
Performance
- Animate
transformandopacityonly (GPU-composited). Avoid animatingwidth/height/top/left/margin(layout thrash) — usescale/x/yorlayout. - Reduce bundle: use
LazyMotion+domAnimationand the lightweightmcomponent instead ofmotionwhere you don't need the full feature set:
import { LazyMotion, domAnimation, m } from 'motion/react'
<LazyMotion features={domAnimation}><m.div animate={{ opacity: 1 }} /></LazyMotion>
- Springs (
type: 'spring') feel natural; tweens (duration,ease) for precise timing. Stagger lists rather than animating dozens of springs independently. - On constrained devices (Smart TV, low-end mobile) prefer CSS transitions or minimal opacity/transform; heavy
layout/spring work can jank.
Next.js App Router (RSC)
motion/m components are interactive → they require "use client". Put them in client components; don't import motion into a Server Component. A common pattern is a small MotionDiv client wrapper re-exported for use inside server pages.
Don'ts
- Don't animate layout-triggering CSS props for transitions.
- Don't forget
key+AnimatePresencefor exit animations (they silently won't run otherwise). - Don't ignore reduced-motion.
- Don't import the full
motioneverywhere whenLazyMotion+mwould cut bundle size. - Don't mix
framer-motionandmotionpackages in one app.