React Animations with Framer Motion

A comprehensive guide to react animations with framer motion with production examples and best practices.

Why Framer Motion Over Raw CSS Animations

Raw CSS animations and transitions work fine for simple hover effects or fade-ins. But when you need orchestrated sequences, gesture-driven interactions, or layout animations that respond to state changes, you quickly hit limitations. Framer Motion abstracts the complexity of the Web Animations API and provides a declarative, component-based approach. It handles spring physics, keyframes, variants, and exit animations out of the box. In production, the biggest win is predictable timing and easing — no more magic numbers or janky transitions. You get a unified API for enter, update, and exit animations, which reduces bugs and improves developer velocity. If your React app has more than a handful of animated elements, Framer Motion pays for itself in maintainability.

import { motion } from 'framer-motion';

export default function BasicFade() {
  return (
    <motion.div
      initial={{ opacity: 0 }}
      animate={{ opacity: 1 }}
      transition={{ duration: 0.5 }}
    >
      Hello World
    </motion.div>
  );
}

Setting Up Motion Components

Framer Motion exports a motion object that wraps standard HTML and SVG elements. Instead of <div>, you write <motion.div>. This gives you access to props like initial, animate, exit, whileHover, whileTap, and transition. The initial prop defines the starting state, animate defines the end state, and transition controls timing and easing. You can also use variants to define named animation states and reuse them across components. In production, always define variants outside the component to avoid re-creating objects on every render. This prevents unnecessary re-renders and keeps your animation definitions clean.

import { motion } from 'framer-motion';

const variants = {
  hidden: { opacity: 0, y: 20 },
  visible: { opacity: 1, y: 0 },
};

export default function Card({ children }) {
  return (
    <motion.div
      variants={variants}
      initial="hidden"
      animate="visible"
      transition={{ duration: 0.3 }}
    >
      {children}
    </motion.div>
  );
}

Orchestrating Sequences with Variants

Variants are the backbone of Framer Motion's orchestration. You can define multiple states (e.g., hidden, visible, hovered) and transition between them. The real power comes from transition properties like staggerChildren, delayChildren, and when. staggerChildren staggers the animation of child elements by a specified delay. delayChildren adds a delay before children start animating. when can be beforeChildren or afterChildren to control ordering. In production, staggering is essential for list animations — it prevents all items from animating at once, which looks jarring. Use staggerChildren with a small delay (e.g., 0.05s) for smooth, natural-feeling sequences.

import { motion } from 'framer-motion';

const container = {
  hidden: {},
  visible: {
    transition: { staggerChildren: 0.1 },
  },
};

const item = {
  hidden: { opacity: 0, y: 20 },
  visible: { opacity: 1, y: 0 },
};

export default function List({ items }) {
  return (
    <motion.ul variants={container} initial="hidden" animate="visible">
      {items.map((text, i) => (
        <motion.li key={i} variants={item}>
          {text}
        </motion.li>
      ))}
    </motion.ul>
  );
}

Gesture-Driven Animations

Framer Motion supports gestures like hover, tap, drag, and pan via props like whileHover, whileTap, whileDrag, and whileFocus. These are essential for interactive UI elements. For example, a button can scale up on hover and scale down on tap. The drag prop enables drag-and-drop with constraints and momentum. In production, gesture animations must be performant — avoid animating layout properties (width, height) during drag; use transform instead. Also, set dragElastic to a small value (e.g., 0.2) to prevent the element from flying off-screen. Always test gesture animations on mobile devices where touch events can be janky.

import { motion } from 'framer-motion';

export default function GestureButton() {
  return (
    <motion.button
      whileHover={{ scale: 1.05 }}
      whileTap={{ scale: 0.95 }}
      transition={{ type: 'spring', stiffness: 400, damping: 10 }}
    >
      Click Me
    </motion.button>
  );
}

Layout Animations with AnimatePresence

AnimatePresence enables exit animations when components are removed from the React tree. Wrap a group of elements with AnimatePresence and use the exit prop on motion components to define their leaving animation. This is critical for modals, notifications, and lists where items can be deleted. Without it, elements just disappear. In production, always set a key on animated children so React can track them. Also, use mode="wait" to prevent the next element from animating in before the current one exits. This avoids visual overlap and race conditions.

import { motion, AnimatePresence } from 'framer-motion';
import { useState } from 'react';

export default function Notifications() {
  const [items, setItems] = useState([1, 2, 3]);

  const removeItem = (id) => setItems(items.filter(i => i !== id));

  return (
    <AnimatePresence>
      {items.map(id => (
        <motion.div
          key={id}
          initial={{ opacity: 0, x: 100 }}
          animate={{ opacity: 1, x: 0 }}
          exit={{ opacity: 0, x: -100 }}
          transition={{ duration: 0.2 }}
          onClick={() => removeItem(id)}
        >
          Item {id}
        </motion.div>
      ))}
    </AnimatePresence>
  );
}

Spring Physics vs. Tween Transitions

Framer Motion offers two main transition types: tween (eased) and spring (physics-based). Tween uses cubic bezier curves and is predictable — good for UI elements that need to match a design spec. Spring uses mass, stiffness, and damping to create natural, bouncy motion. Spring feels more organic but can overshoot. In production, use spring for gestures and micro-interactions (buttons, toggles) and tween for page transitions and layout animations where you need exact timing. Avoid spring for large elements or frequent updates — the physics calculations can cause jank on low-end devices. Test both on target hardware.

import { motion } from 'framer-motion';

export default function Compare() {
  return (
    <>
      <motion.div
        animate={{ x: 100 }}
        transition={{ type: 'tween', duration: 0.5, ease: 'easeInOut' }}
      >
        Tween
      </motion.div>
      <motion.div
        animate={{ x: 100 }}
        transition={{ type: 'spring', stiffness: 100, damping: 10 }}
      >
        Spring
      </motion.div>
    </>
  );
}

Animating SVG Elements

Framer Motion works seamlessly with SVG elements like <motion.circle>, <motion.path>, and <motion.g>. You can animate SVG-specific attributes like pathLength, strokeDasharray, and fill. This is perfect for loading indicators, icons, and data visualizations. For path drawing animations, use pathLength with initial={{ pathLength: 0 }} and animate={{ pathLength: 1 }}. In production, SVG animations can be GPU-accelerated by animating transform and opacity instead of layout properties. Also, keep SVG complexity low — too many nodes will tank performance. Use will-change: transform on the SVG container to hint the browser.

import { motion } from 'framer-motion';

export default function DrawCircle() {
  return (
    <svg width="100" height="100" viewBox="0 0 100 100">
      <motion.circle
        cx="50" cy="50" r="40"
        fill="none"
        stroke="#00cc88"
        strokeWidth="4"
        initial={{ pathLength: 0 }}
        animate={{ pathLength: 1 }}
        transition={{ duration: 2 }}
      />
    </svg>
  );
}

Performance Optimization and Debugging

Animations can cause jank if not optimized. Key strategies: (1) Animate only transform and opacity — these are composited by the GPU. Avoid animating width, height, top, left as they trigger layout recalculations. (2) Use layout prop for layout animations — Framer Motion will animate changes using transform under the hood. (3) Set will-change: transform on elements that animate. (4) Use motion components sparingly — each one adds overhead. (5) Profile with React DevTools and Chrome Performance tab. In production, we once had a page with 200 animated elements — switching to transform animations and reducing the number of simultaneous animations fixed the jank.

import { motion } from 'framer-motion';

export default function OptimizedBox() {
  return (
    <motion.div
      style={{ willChange: 'transform' }}
      animate={{ scale: 1.2 }}
      transition={{ type: 'spring', stiffness: 300, damping: 20 }}
    >
      Optimized
    </motion.div>
  );
}

Testing Animations in CI/CD

Animations are notoriously hard to test. In CI/CD, you can use jest with @testing-library/react and mock Framer Motion to avoid timing issues. For visual regression, use tools like Percy or Chromatic. For interaction tests, use userEvent and wait for animations to settle with waitFor. In production, we added a data-testid to animated elements and used jest.mock('framer-motion', () => ({ motion: { div: 'div' } })) to strip animations in unit tests. For end-to-end tests with Cypress, disable animations globally with cy.clock() and cy.tick() to control time. Never rely on animation timing in tests — always wait for specific states.

import { render, screen, waitFor } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import MyComponent from './MyComponent';

jest.mock('framer-motion', () => ({
  motion: { div: 'div' },
  AnimatePresence: ({ children }) => children,
}));

test('button click triggers state change', async () => {
  render(<MyComponent />);
  const button = screen.getByRole('button');
  await userEvent.click(button);
  await waitFor(() => {
    expect(screen.getByText('Active')).toBeInTheDocument();
  });
});

Common Pitfalls and How to Avoid Them

Pitfall 1: Animating height: auto — Framer Motion cannot animate to auto. Use maxHeight or a fixed height. Pitfall 2: Forgetting to set key on children in AnimatePresence — exit animations break. Pitfall 3: Using initial={false} to skip initial animation — this can cause unexpected jumps if not handled correctly. Pitfall 4: Overusing layout prop — it can cause performance issues if many elements animate layout simultaneously. Pitfall 5: Not handling reduced motion preferences — use useReducedMotion() hook to respect user settings. In production, we saw a user with vestibular disorder complain about our animations. Adding useReducedMotion() and disabling all non-essential animations resolved the issue.

import { motion, useReducedMotion } from 'framer-motion';

export default function SafeAnimation() {
  const prefersReducedMotion = useReducedMotion();

  const animation = prefersReducedMotion
    ? { opacity: 1 }
    : { opacity: 1, x: 100 };

  return <motion.div animate={animation}>Content</motion.div>;
}

Integrating with React Router for Page Transitions

Page transitions are a common use case. Use AnimatePresence with useLocation and useRoutes to animate route changes. Wrap your route outlet with AnimatePresence and use motion.div with key set to the location pathname. Define initial, animate, and exit for page-level animations. In production, be careful with scroll position — when a new page enters, scroll should reset to top. Use useEffect or useLayoutEffect to scroll to top on route change. Also, avoid animating large page layouts — animate only the content area to keep performance high.

import { motion, AnimatePresence } from 'framer-motion';
import { useLocation, Routes, Route } from 'react-router-dom';

export default function AnimatedRoutes() {
  const location = useLocation();

  return (
    <AnimatePresence mode="wait">
      <motion.div
        key={location.pathname}
        initial={{ opacity: 0, y: 20 }}
        animate={{ opacity: 1, y: 0 }}
        exit={{ opacity: 0, y: -20 }}
        transition={{ duration: 0.3 }}
      >
        <Routes location={location}>
          <Route path="/" element={<Home />} />
          <Route path="/about" element={<About />} />
        </Routes>
      </motion.div>
    </AnimatePresence>
  );
}

Production Checklist for Framer Motion

Before shipping, run through this checklist: (1) All animations respect prefers-reduced-motion via useReducedMotion(). (2) No layout-triggering properties animated — use transform and opacity. (3) AnimatePresence has mode="wait" where appropriate. (4) Variants defined outside components. (5) Keys are stable and unique for animated lists. (6) Performance profiled on target devices — especially low-end mobile. (7) Animations disabled in unit tests via mock. (8) No infinite loops — animate props should not change on every render. (9) will-change set on animated elements. (10) Accessibility — animations are not essential for understanding content. Following this checklist prevents the most common production issues we've encountered.

// Example of a production-ready animated component
import { motion, useReducedMotion } from 'framer-motion';

const variants = {
  hidden: { opacity: 0 },
  visible: { opacity: 1 },
};

export default function SafeComponent({ children }) {
  const prefersReducedMotion = useReducedMotion();

  return (
    <motion.div
      variants={variants}
      initial="hidden"
      animate="visible"
      transition={prefersReducedMotion ? { duration: 0 } : { duration: 0.3 }}
      style={{ willChange: 'transform' }}
    >
      {children}
    </motion.div>
  );
}

Motion Library Rebrand

Framer Motion has rebranded its package from 'framer-motion' to 'motion' for React projects. The new import path is 'motion/react' instead of 'framer-motion'. This change simplifies the library name and aligns with its expansion beyond React. To migrate, update your imports: replace import { motion } from 'framer-motion' with import { motion } from 'motion/react'. All existing APIs remain unchanged, so you can continue using the same components and hooks. This rebrand does not affect functionality but ensures compatibility with future updates. For TypeScript users, types are now exported from 'motion/react' as well. Example: import { motion, AnimatePresence } from 'motion/react'. Note that the old package will still work but may not receive new features. It's recommended to update your package.json and imports as soon as possible.

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

function App() {
  return (
    <motion.div
      initial={{ opacity: 0 }}
      animate={{ opacity: 1 }}
    >
      Hello Motion
    </motion.div>
  );
}

animateView API

The animateView API provides a declarative way to animate view transitions in React. It leverages the View Transitions API (available in Chromium-based browsers) to create smooth, native-like transitions between pages or components. To use it, wrap your transition target with animateView and define the animation using initial, animate, and exit props, similar to motion components. The key difference is that animateView works with the browser's view transition mechanism, enabling cross-document animations and shared element transitions. Example: import { animateView } from 'motion/react' then use <animateView.div initial={{ opacity: 0 }} animate={{ opacity: 1 }}>. For page transitions, pair it with React Router by wrapping route components. Note that browser support is limited; provide a fallback for non-supporting browsers. The API also supports viewTransition prop for customizing the transition name and duration.

import { animateView } from 'motion/react';
import { Routes, Route, useLocation } from 'react-router-dom';

function AnimatedRoutes() {
  const location = useLocation();
  return (
    <animateView.div
      key={location.pathname}
      initial={{ opacity: 0, scale: 0.9 }}
      animate={{ opacity: 1, scale: 1 }}
      exit={{ opacity: 0, scale: 0.9 }}
      viewTransition={{ name: 'page-transition' }}
    >
      <Routes location={location}>
        <Route path="/" element={<Home />} />
        <Route path="/about" element={<About />} />
      </Routes>
    </animateView.div>
  );
}

ViewTimeline for Scroll-Linked Animations

The useScroll hook in Framer Motion now supports scroll-linked animations via the ViewTimeline API. This allows you to tie animations directly to scroll progress without manual calculation. Use useScroll with the container option to track a specific scroll container, and combine it with useTransform to map scroll progress to animation values. For example, you can animate an element's opacity based on its visibility in the viewport. The hook returns scrollYProgress (0 to 1) which you can feed into useTransform. For more complex scroll-linked effects, use the offset option to define start and end points. Example: const { scrollYProgress } = useScroll({ target: ref, offset: ['start end', 'end start'] }). This is more performant than scroll event listeners because it uses the Intersection Observer and requestAnimationFrame under the hood.

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

function ScrollAnimation() {
  const ref = useRef(null);
  const { scrollYProgress } = useScroll({
    target: ref,
    offset: ['start end', 'end start']
  });
  const opacity = useTransform(scrollYProgress, [0, 0.5, 1], [0, 1, 0]);
  const scale = useTransform(scrollYProgress, [0, 0.5, 1], [0.8, 1, 0.8]);

  return (
    <motion.div ref={ref} style={{ opacity, scale }}>
      Scroll-linked content
    </motion.div>
  );
}

New Color Types

Framer Motion now supports modern CSS color spaces including oklch, lab, and color-mix. This allows for more perceptually uniform color interpolation and richer color palettes. You can use these color types directly in animate props, variants, or style objects. For example, animate={{ backgroundColor: 'oklch(0.7 0.2 240)' }} will smoothly transition between oklch colors. The library automatically handles interpolation between different color spaces, converting them to a common space for smooth animation. This is particularly useful for design systems that use oklch for consistent lightness. Note that browser support for these color spaces is growing; Framer Motion will fall back to sRGB if unsupported. Example: motion.div animate={{ color: 'color-mix(in oklch, red, blue)' }}. You can also use these in useTransform for dynamic color changes.

import { motion } from 'motion/react';

function ColorAnimation() {
  return (
    <motion.div
      initial={{ backgroundColor: 'oklch(0.8 0.1 120)' }}
      animate={{ backgroundColor: 'oklch(0.5 0.3 240)' }}
      transition={{ duration: 2 }}
    >
      Oklch Color Transition
    </motion.div>
  );
}