Motion Animation Patterns

Quick Guide: Use Motion for declarative React animations. motion.* components for basic animations, variants for orchestrated sequences, AnimatePresence for exit animations, layout/layoutId for FLIP animations, useScroll/useInView for scroll-triggered effects. Always animate transform properties (x, y, scale, rotate, opacity) for GPU performance. Always respect reduced motion via MotionConfig reducedMotion="user".

Import: import { motion } from "motion/react" (v11+ package rename from framer-motion)

---

<critical_requirements>

CRITICAL: Before Using This Skill

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering, import type, named constants)

(You MUST wrap exiting components in AnimatePresence for exit animations to work)

(You MUST provide unique key prop to direct children of AnimatePresence)

(You MUST animate transform properties (x, y, scale, rotate, opacity) for GPU-accelerated performance)

(You MUST respect reduced motion preferences using MotionConfig or useReducedMotion)

(You MUST use named constants for all animation timing values - NO magic numbers)

</critical_requirements>

---

Auto-detection: Motion, Framer Motion, motion.div, motion.button, AnimatePresence, useAnimation, useScroll, useInView, usePageInView, variants, whileHover, whileTap, layoutId, spring, tween, stagger, "motion/react", "framer-motion"

When to use:

• Animating component enter/exit/presence
• Orchestrating complex multi-element animations with variants
• Implementing gesture-based interactions (hover, tap, drag)
• Creating scroll-triggered or scroll-linked animations
• Animating layout changes and shared element transitions
• Building micro-interactions and UI feedback

When NOT to use:

• Simple CSS transitions (use CSS transitions instead)
• Complex timeline-based animations requiring frame-level control (consider a dedicated timeline animation library)
• Performance-critical animations on low-powered devices without careful optimization

Key patterns covered:

• motion components and animation props (initial, animate, exit, transition)
• Variants for reusable, orchestrated animations
• AnimatePresence for exit animations and animation modes
• Gesture props (whileHover, whileTap, whileDrag, drag)
• Layout animations (layout prop, layoutId, LayoutGroup)
• Scroll animations (useScroll, useInView, whileInView)
• Spring and tween transitions
• useAnimation for imperative control
• Reduced motion accessibility
• v12: usePageInView, enhanced stagger(), drag stop/cancel

---

Detailed Resources:

• examples/core.md - Motion components, variants, AnimatePresence, gestures, accessibility
• examples/layout.md - Layout animations, shared elements, expandable cards
• examples/scroll.md - Scroll progress, reveal, parallax
• examples/sequences.md - Complex sequences, keyframes
• examples/svg.md - SVG path animations
• reference.md - Decision frameworks, migration guide, anti-patterns, performance, quick reference

---

<philosophy>

Philosophy

Motion is a declarative animation library for React that makes animations feel natural and accessible. It uses a physics-based approach with spring animations as defaults, creating fluid motion that matches real-world expectations.

Core principles:

1. Declarative over imperative - Describe what the animation should look like, not how to achieve it
2. Props over keyframes - Use initial, animate, exit props instead of CSS keyframes
3. Variants for orchestration - Group related animations and control timing with parent-child relationships
4. Performance through transforms - Animate GPU-accelerated properties (transform, opacity) for smooth 60fps
5. Accessibility built-in - Respect user preferences for reduced motion

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Basic Motion Components

Prefix any HTML or SVG element with motion. to make it animatable. Use initial, animate, exit, and transition props.

import { motion } from "motion/react";

const FADE_DURATION_S = 0.3;
const SLIDE_DISTANCE_PX = 20;

export const FadeIn = ({ children }: { children: React.ReactNode }) => (
  <motion.div
    initial={{ opacity: 0, y: SLIDE_DISTANCE_PX }}
    animate={{ opacity: 1, y: 0 }}
    transition={{ duration: FADE_DURATION_S }}
  >
    {children}
  </motion.div>
);

Why good: Named constants, declarative intent, y is GPU-accelerated (never animate top/left/margin)

See examples/core.md Pattern 1 for full examples with className, delay props, and bad examples.

---

Pattern 2: Variants for Orchestrated Animations

Variants define reusable animation states and enable parent-child orchestration with staggerChildren.

import { motion, type Variants } from "motion/react";

const STAGGER_DELAY_S = 0.1;

const ITEM_DISTANCE_PX = 20;

const containerVariants: Variants = {
  hidden: { opacity: 0 },
  visible: { opacity: 1, transition: { staggerChildren: STAGGER_DELAY_S } },
};

const itemVariants: Variants = {
  hidden: { opacity: 0, y: ITEM_DISTANCE_PX },
  visible: { opacity: 1, y: 0 },
};

Children automatically inherit animation state from parent. Use staggerDirection: -1 for reverse stagger on exit.

See examples/core.md Pattern 2 for complete list animation with exit variants.

---

Pattern 3: AnimatePresence for Exit Animations

AnimatePresence enables exit animations for components being removed from the React tree. Direct children must have unique key props.

import { AnimatePresence, motion } from "motion/react";

const MODAL_SCALE_HIDDEN = 0.95;

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

Animation modes: mode="sync" (default, simultaneous), mode="wait" (wait for exit before enter - ideal for page transitions), mode="popLayout" (for shared layout transitions).

See examples/core.md Pattern 3 for modal and page transition examples.

---

Pattern 4: Gesture Animations

Gesture props enable hover, tap, focus, and drag interactions.

const HOVER_SCALE = 1.05;
const TAP_SCALE = 0.95;
const GESTURE_SPRING = { type: "spring" as const, stiffness: 400, damping: 17 };

<motion.button
  whileHover={{ scale: HOVER_SCALE }}
  whileTap={{ scale: TAP_SCALE }}
  transition={GESTURE_SPRING}
/>

For drag: use drag, dragConstraints, dragElastic, whileDrag. Use useDragControls for programmatic drag (v12+ adds .stop()/.cancel()).

See examples/core.md Pattern 4 for interactive card and draggable element examples.

---

Pattern 5: Layout Animations

The layout prop animates layout changes automatically using FLIP technique. Use layout="position" on children to prevent text distortion. Use layoutId for shared element transitions across different containers.

<motion.div layout transition={LAYOUT_SPRING}>
  <motion.h2 layout="position">Title</motion.h2>
</motion.div>

// Shared element: layoutId creates seamless transitions
{activeTab === tab && <motion.div layoutId="indicator" />}

Use LayoutGroup with id prop to scope layoutId to component instances (layoutId is global by default).

See examples/layout.md for expandable cards and tab indicator examples.

---

Pattern 6: Scroll-Triggered Animations

whileInView for scroll-triggered animations. useScroll + useTransform for scroll-linked effects.

const REVEAL_DISTANCE_PX = 50;
const PARALLAX_RANGE_PX = 100;

// Scroll-triggered (fires once)
<motion.div
  initial={{ opacity: 0, y: REVEAL_DISTANCE_PX }}
  whileInView={{ opacity: 1, y: 0 }}
  viewport={{ once: true, margin: "-100px" }}
/>

// Scroll-linked (continuous)
const { scrollYProgress } = useScroll({ target: ref, offset: ["start end", "end start"] });
const y = useTransform(scrollYProgress, [0, 1], [-PARALLAX_RANGE_PX, PARALLAX_RANGE_PX]);

Motion values from useScroll update without React re-renders.

See examples/scroll.md for progress bar, parallax, and reveal examples.

---

Pattern 7: Spring and Tween Transitions

// Springs - physics-based, natural feel
const BOUNCY = { type: "spring", stiffness: 300, damping: 10 }; // Playful
const SNAPPY = { type: "spring", stiffness: 500, damping: 30 }; // Responsive
const GENTLE = { type: "spring", stiffness: 100, damping: 20 }; // Subtle

// Tweens - duration-based, precise control
const ENTER = { type: "tween", ease: "easeOut", duration: 0.3 }; // Enter
const EXIT = { type: "tween", ease: "easeIn", duration: 0.2 }; // Exit

Rule of thumb: Springs for interactive elements (buttons, cards), tweens for UI transitions (modals, page changes).

See reference.md for full transition type reference with additional presets.

---

Pattern 8: useAnimation for Imperative Control

Use useAnimation when you need programmatic control over animations triggered by external events, complex sequences, or start/stop behavior.

const SHAKE_DISTANCE_PX = 10;
const SHAKE_DURATION_S = 0.3;

const controls = useAnimation();

useEffect(() => {
  if (hasError) {
    controls.start({
      x: [0, -SHAKE_DISTANCE_PX, SHAKE_DISTANCE_PX, -SHAKE_DISTANCE_PX, 0],
      transition: { duration: SHAKE_DURATION_S },
    });
  }
}, [hasError, controls]);

<motion.div animate={controls}>{children}</motion.div>

See examples/sequences.md for multi-step sequences and keyframe animations.

---

Pattern 9: Reduced Motion Accessibility

Always respect user preferences for reduced motion.

// Site-wide: wrap app root
<MotionConfig reducedMotion="user">{children}</MotionConfig>

// Per-component: custom handling
const FULL_DISTANCE_PX = 50;
const FULL_DURATION_S = 0.5;
const REDUCED_DURATION_S = 0.2;

const shouldReduceMotion = useReducedMotion();
<motion.div
  initial={{ opacity: 0, y: shouldReduceMotion ? 0 : FULL_DISTANCE_PX }}
  animate={{ opacity: 1, y: 0 }}
  transition={{ duration: shouldReduceMotion ? REDUCED_DURATION_S : FULL_DURATION_S }}
/>

MotionConfig reducedMotion="user" automatically disables transform/layout animations when reduced motion is preferred. Opacity and color animations still work.

See examples/core.md Pattern 5 for complete accessible animation component.

---

Pattern 10: v12 Features

usePageInView (v12.19+): Detect when page/tab is visible to pause animations or videos in background tabs. Returns boolean, defaults to true on server.

import { usePageInView } from "motion/react";
const isPageVisible = usePageInView();

Enhanced stagger() (v12+): Pass stagger() to delayChildren in variants for from and ease options.

import { stagger } from "motion/react";

// stagger() is passed to delayChildren, NOT staggerChildren
const transition = {
  delayChildren: stagger(0.05, { from: "center", ease: "easeOut" }),
};
// from options: "first" (default), "center", "last", or number (index)

Drag Controls (v12+): useDragControls gains .stop() and .cancel() methods.

</patterns>

---

<red_flags>

RED FLAGS

High Priority Issues:

• Missing AnimatePresence for exit animations - exit prop has no effect without it
• Missing unique key on AnimatePresence children - cannot track elements
• Animating layout-triggering properties (height, width, top, left, margin, padding) - use transform (x, y, scale) instead
• Magic numbers for timing values - all durations, delays, distances must be named constants
• Ignoring reduced motion - always use MotionConfig reducedMotion="user" or useReducedMotion

Medium Priority Issues:

• Using index as key in animated lists - causes incorrect animations when list changes
• Missing layout="position" on children during parent layout animation - children will distort
• Overusing willChange - creates GPU layers; Motion handles optimization automatically
• Not cleaning up useAnimation in useEffect - can cause memory leaks

Gotchas & Edge Cases:

• layoutId is global - use LayoutGroup with id prop to scope to component instances
• AnimatePresence mode="wait" blocks enter until exit completes - may cause perceived delay
• whileInView uses viewport not offset for configuration (unlike useScroll)
• SVG animations require motion.path, motion.circle, etc. - regular SVG elements won't animate
• useInView returns false on server - default to visible state for SSR
• Motion values don't trigger re-renders (by design) - use useMotionValueEvent for side effects
• React Fragments inside AnimatePresence break tracking - each direct child must have a key
• drag with layout can conflict - disable layout during drag or use dragListener
• Spring animations can overshoot - high stiffness + low damping; test with real content
• v12 stagger() goes on delayChildren, not staggerChildren - they serve different purposes

</red_flags>

---

<critical_reminders>

CRITICAL REMINDERS

All code must follow project conventions in CLAUDE.md

(You MUST wrap exiting components in AnimatePresence for exit animations to work)

(You MUST provide unique key prop to direct children of AnimatePresence)

(You MUST animate transform properties (x, y, scale, rotate, opacity) for GPU-accelerated performance)

(You MUST respect reduced motion preferences using MotionConfig or useReducedMotion)

(You MUST use named constants for all animation timing values - NO magic numbers)

Failure to follow these rules will break exit animations, cause performance issues, and create inaccessible experiences.

</critical_reminders>