Motion (formerly Framer Motion)
−Production-ready animation library for React. Motion (published as the `motion` package) is the default choice for component-level animation: enter/exit transitions, layout shifts, gesture responses, spring physics, and scroll-linked effects. It integrates deeply with React's component model and handles the hard parts — interrupted animations, layout measurement, exit choreography — so you can focus on feel.
+Production-ready animation library for React. Motion (npm package: `motion`) is the default choice for component-level animation: enter/exit transitions, layout shifts, gesture responses, spring physics, and scroll-linked effects. It integrates with React's component model and handles interrupted animations, layout measurement, and exit choreography so you can focus on feel.
−> Note: The project publishes as Motion (npm package name: `motion`, docs: motion.dev). The legacy `framer-motion` package remains available for migration, but prefer the newer `motion` packages and docs on motion.dev. Import React bindings from `motion/react`.
+Note: The project publishes as Motion (package name: `motion`). Import React bindings from `motion/react` (e.g. `import { motion, AnimatePresence } from 'motion/react'`). The legacy `framer-motion` package remains published for compatibility but prefer `motion` and the docs on motion.dev for new projects.
−## When to use
+When to use
- Component mount/unmount transitions (modals, toasts, dropdowns, page transitions)
- Layout animations when elements reorder, resize, or move across containers
- Hover, tap, drag, and focus micro-interactions
- Shared element transitions across routes (with `layoutId`)
- Spring-based physics for interactive feel (sliders, toggles, cards)
−- Scroll-linked opacity or parallax on individual elements
+- Scroll-linked effects on individual elements (use `useScroll`, ViewTimeline)
−## When NOT to use
+When NOT to use
+- Scroll-driven pinning/scrubbing or full-page scrollytelling — prefer GSAP + ScrollTrigger for high-control scrub timelines
+- Complex multi-surface orchestration (DOM + Canvas + WebGL) — use a timeline-focused library (GSAP) or coordinate distinct render layers
+- Non-React projects — Motion is React-first; use Motion’s vanilla APIs or other libraries for other frameworks
+- CSS-only hover states where a 1–2 line CSS transition suffices
−- Scroll-driven pinning, scrubbing, or multi-section choreography — use GSAP + ScrollTrigger
+- Very large lists with thousands of concurrent animated targets — profile first and prefer virtualized approaches
−- Complex multi-surface orchestration (DOM + Canvas + WebGL simultaneously) — use GSAP timelines
−- Non-React projects — Motion is React-first; use Motion's vanilla API or other libraries for other frameworks
−- CSS-only hover states where a 2-line transition suffices — do not over-engineer
−- Performance-critical loops rendering thousands of animated items — profile first
−## Core concepts
+Core concepts
−### motion components
+motion components
−Wrap any HTML or SVG element with animation superpowers:
+Wrap HTML or SVG elements with animation capabilities:
−```tsx
+import { motion } from 'motion/react';
−import { motion } from "motion/react";
−<motion.div
+<motion.div initial={{ opacity: 0 }} animate={{ opacity: 1 }} exit={{ opacity: 0 }} />
− initial={{ opacity: 0 }}
− animate={{ opacity: 1 }}
− exit={{ opacity: 0 }}
−/>
−```
−(Install: `npm install motion`. Import React bindings from `motion/react`.)
+Variants
−
−### Variants
Named animation states that propagate through component trees — use them for staggered entrances and shared state.
−### AnimatePresence
+AnimatePresence
−Animate components as they unmount:
+Wrap conditionally mounted children to run exit animations:
−```tsx
+import { AnimatePresence } from 'motion/react';
−import { AnimatePresence } from "motion/react";
−<AnimatePresence mode="wait">
+<AnimatePresence mode="wait">{isOpen && <motion.div key="modal" initial={{ opacity: 0 }} animate={{ opacity: 1 }} exit={{ opacity: 0 }} />}</AnimatePresence>
− {isOpen && (
− <motion.div
− key="modal"
− initial={{ opacity: 0, scale: 0.95 }}
− animate={{ opacity: 1, scale: 1 }}
− exit={{ opacity: 0, scale: 0.95 }}
− transition={{ duration: 0.2 }}
− />
− )}
−</AnimatePresence>
−```
−Remember: every direct child of AnimatePresence needs a stable `key` for exit animations to run.
+Each direct child of AnimatePresence must have a stable `key` for exit choreography to run.
−### Layout animations
+Layout animations
Automatic interpolation when elements change position or size:
−```tsx
+<motion.div layout className={isExpanded ? 'w-full' : 'w-48'}>
−<motion.div layout className={isExpanded ? "w-full" : "w-48"}>
<motion.p layout="position">Content stays in place</motion.p>
</motion.div>
−```
−Recent March 2026 patch series (Mar 3–16, 2026) delivered several important improvements to layout projection, color handling, and scroll-linked timelines. See the Motion changelog (https://motion.dev/changelog) for full release notes.
+Use axis-locked layout (layout="x" / layout="y") when only one axis should animate.
−### Shared layout with layoutId
+Shared layout with layoutId
−Seamless element transitions across different components:
+Seamless transitions across different components using `layoutId` on both source and destination elements.
−```tsx
+Spring configuration
−{items.map((item) => (
− <motion.div key={item.id} layoutId={item.id} onClick={() => setSelected(item)}>
− {item.title}
− </motion.div>
−))}
−{selected && (
+Tune stiffness, damping, and mass for desired feel. Example:
− <motion.div layoutId={selected.id} className="expanded-card">
