Animation Guide

A practical guide to building accessible, performant animations with Framer Motion. Covers when to animate, what to animate, performance budgets, accessibility requirements, and debugging techniques.

Table of Contents

1. When to Animate

2. Choosing the Right Pattern

3. Performance Budget

4. Accessibility Requirements

5. Spring vs. Tween

6. Common Mistakes

7. Debugging Animations

8. Browser Compatibility

When to Animate

Animate When...

Don't Animate When...

The 3-Second Rule

If an animation takes longer than 3 seconds to complete (including stagger), it's too long. Users lose patience after 3 seconds. The ideal animation:

• Micro-interaction: 150-300ms
• Entrance: 300-600ms
• Page transition: 300-500ms
• Stagger total: Under 500ms
• Loading skeleton: Until data arrives (but with calm animation)

Choosing the Right Pattern

Decision Tree

Is the element entering the viewport for the first time?
├── YES → Is it triggered by scroll?
│   ├── YES → ScrollReveal component
│   └── NO → Entrance variant (fadeUp, scaleUp, etc.)
└── NO → Is the element responding to user interaction?
    ├── YES → Is it a hover/tap?
    │   ├── YES → Hover variant (lift, press, grow, etc.)
    │   └── NO → useMicroInteraction hook
    └── NO → Is the element leaving?
        ├── YES → Exit variant + AnimatePresence
        └── NO → Is it a layout change?
            ├── YES → layout prop + LayoutGroup
            └── NO → You probably don't need animation here

Pattern Recommendations by Context

Performance Budget

The 16ms Frame Budget

At 60fps, each frame has 16.67ms. Your animation logic must complete within this budget:

16ms total frame budget
├── 2-4ms   JavaScript (animation calculations)
├── 2-4ms   Style recalculation
├── 2-4ms   Layout (if properties change layout)
├── 2-4ms   Paint (if properties need repainting)
└── 2-4ms   Compositing (GPU layer management)

Properties by Cost

Rules

1. Only animate transform and opacity for the smoothest results

2. Use will-change: transform to hint the browser (the variants in this pack do this automatically)

3. Limit will-change to 3-5 elements — too many promoted layers waste GPU memory

4. Avoid animating during scroll unless using useScroll() (passive, RAF-based)

5. Test on low-end devices — your MacBook Pro is not representative

Measuring Performance

// In Chrome DevTools:
// 1. Open Performance panel
// 2. Enable "Screenshots" and "Web Vitals"
// 3. Click Record, trigger your animation, stop
// 4. Look for:
//    - Long frames (red bars above 16ms)
//    - Layout shifts (yellow "Layout" blocks)
//    - Paint events (green blocks — should be rare during animation)

// Programmatically:
const observer = new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    if (entry.duration > 16) {
      console.warn(`Long frame: ${entry.duration.toFixed(1)}ms`, entry);
    }
  }
});
observer.observe({ type: 'longtask', buffered: true });

Accessibility Requirements

prefers-reduced-motion

This is not optional. Approximately 25-35% of users have motion sensitivity to some degree. Vestibular disorders can cause nausea, dizziness, and migraines from screen motion.

Every animation in this pack respects prefers-reduced-motion: reduce automatically. Here's what happens:

Testing Reduced Motion

macOS: System Settings → Accessibility → Display → Reduce motion

Windows: Settings → Ease of Access → Display → Show animations → Off

Chrome DevTools: Rendering → Emulate CSS media feature → prefers-reduced-motion: reduce

WCAG Compliance

• 2.3.1 Three Flashes: No content flashes more than 3 times per second
• 2.3.3 Animation from Interactions: Provide mechanism to disable non-essential animation
• 2.2.2 Pause, Stop, Hide: Moving content can be paused by the user

The ReducedMotionProvider in this pack satisfies all three criteria when wrapped around your app root.

Spring vs. Tween

When to Use Springs

Springs use physics simulation (stiffness, damping, mass) instead of fixed duration + easing curve.

Use springs for:

• Anything the user interacts with (buttons, cards, toggles)
• Layout animations (things moving to new positions)
• Draggable elements
• Any animation that might be interrupted mid-motion

Why: Springs handle interruption gracefully. If a spring animation is in-flight and you change the target, it smoothly redirects. Tweens jump to the start of the new animation.

When to Use Tweens

Tweens use fixed duration + easing curve (like CSS transitions).

Use tweens for:

• Decorative animations (shimmer, gradient shifts)
• Clip-path reveals (springs don't work well with clip-path)
• Filter animations (blur, brightness)
• Anything with a fixed, predictable duration
• Sequenced animations where timing must be exact

Spring Parameter Cheat Sheet

Use springFromBehavior() from easing.ts to calculate these from desired duration and bounce.

Common Mistakes

1. Animating Layout Properties

// BAD: Animating width causes layout thrashing
<motion.div animate={{ width: isOpen ? 300 : 0 }} />

// GOOD: Animate scaleX instead (GPU composited)
<motion.div animate={{ scaleX: isOpen ? 1 : 0 }} style={{ transformOrigin: 'left' }} />

// GOOD: If you must animate width, use layout animation
<motion.div layout style={{ width: isOpen ? 300 : 0 }} />

2. Too Many Simultaneous Animations

// BAD: Every card animates independently on mount
{cards.map(card => (
  <motion.div initial={{ opacity: 0 }} animate={{ opacity: 1 }}>
    {card.title}
  </motion.div>
))}

// GOOD: Use stagger so they animate sequentially
<StaggerList items={cards} staggerDelay={0.06} renderItem={...} />

3. Forgetting AnimatePresence

// BAD: Element unmounts instantly — exit animation never plays
{isVisible && <motion.div exit={{ opacity: 0 }}>Content</motion.div>}

// GOOD: AnimatePresence keeps element mounted during exit animation
<AnimatePresence>
  {isVisible && (
    <motion.div key="content" exit={{ opacity: 0 }}>Content</motion.div>
  )}
</AnimatePresence>

4. Missing key prop in AnimatePresence

// BAD: No key — AnimatePresence can't track which element is leaving
<AnimatePresence>
  {items.map(item => <motion.div>{item.name}</motion.div>)}
</AnimatePresence>

// GOOD: Unique key lets AnimatePresence track each element
<AnimatePresence>
  {items.map(item => (
    <motion.div key={item.id}>{item.name}</motion.div>
  ))}
</AnimatePresence>

5. Ignoring Reduced Motion

// BAD: No reduced motion consideration
<motion.div animate={{ x: 100, rotate: 360 }} />

// GOOD: Use variants from this pack — they include reduced fallbacks
import { fadeUp } from './variants/entrance';
const prefersReduced = useReducedMotion();
<motion.div {...(prefersReduced ? fadeUp.reduced : fadeUp)} />

Debugging Animations

Chrome DevTools Techniques

1. Slow down animations: Rendering → "Animation slow-down" slider

2. See layer composition: Layers panel → shows which elements are GPU-composited

3. Detect layout shifts: Performance panel → look for yellow "Layout" events during animation

4. Monitor paint: Rendering → "Paint flashing" → green highlights show repaints

Framer Motion Dev Tools

// Log animation lifecycle
<motion.div
  onAnimationStart={() => console.log('Animation started')}
  onAnimationComplete={() => console.log('Animation completed')}
  animate={{ opacity: 1 }}
/>

// Inspect motion values
import { useMotionValue, useTransform } from 'framer-motion';
const x = useMotionValue(0);
x.on('change', (latest) => console.log('x:', latest));

Common Issues & Solutions

Browser Compatibility

All features used in this pack are supported in all modern browsers (released after 2020).

For IE11 support (not recommended), you would need:

• Intersection Observer polyfill
• Web Animations API polyfill
• CSS custom properties polyfill