Framer Motion

Core concepts

motion components

Wrap any HTML or SVG element with animation superpowers:

import { motion } from "motion/react";

<motion.div
  initial={{ opacity: 0 }}
  animate={{ opacity: 1 }}
  exit={{ opacity: 0 }}
/>

(Import path: prefer motion/react — Motion's current docs and installs use the motion package and React bindings at motion/react.)

Variants

Named animation states that propagate through component trees:

const container = {
  hidden: { opacity: 0 },
  visible: {
    opacity: 1,
    transition: { staggerChildren: 0.08 },
  },
};

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

<motion.ul variants={container} initial="hidden" animate="visible">
  {items.map((i) => (
    <motion.li key={i.id} variants={item} />
  ))}
</motion.ul>

AnimatePresence

Animate components as they unmount:

import { AnimatePresence } from "motion/react";

<AnimatePresence mode="wait">
  {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>

Layout animations

Automatic interpolation when elements change position or size:

<motion.div layout className={isExpanded ? "w-full" : "w-48"}>
  <motion.p layout="position">Content stays in place</motion.p>
</motion.div>

Recent Motion releases (March 2026) added more control to layout projection:

• Use layout="x" or layout="y" to lock layout projection to a single axis when only one axis changes (Motion 12.36.0, 2026-03-09).
• layoutAnchor configures the anchor point used to resolve projection boxes (Motion 12.38.0, 2026-03-16).
• dragSnapToOrigin accepts per-axis values ("x"/"y").
• skipInitialAnimation is available on useSpring to avoid the first animation when desired.
• Motion added color-space support (oklch, oklab, lch, lab, etc.) and several Strict Mode and WAAPI fixes in the March 2026 patch series.

Shared layout with layoutId

Seamless element transitions across different components:

{items.map((item) => (
  <motion.div key={item.id} layoutId={item.id} onClick={() => setSelected(item)}>
    {item.title}
  </motion.div>
))}

{selected && (
  <motion.div layoutId={selected.id} className="expanded-card">
    {selected.details}
  </motion.div>
)}

Spring configuration

Presets are a starting point — tune stiffness, damping, and mass for the interaction.

<motion.div
  animate={{ x: 100 }}
  transition={{ type: "spring", stiffness: 300, damping: 25, mass: 0.5 }}
/>

Workflow

1. Identify the animation type: enter/exit, layout shift, gesture response, or scroll-linked. This determines the Motion API to use.
2. Define variants for reusable states; extract to shared files when repeated.
3. Wrap conditional unmounts with <AnimatePresence> and ensure children have stable keys.
4. Tune springs on real devices. Use skipInitialAnimation for cases where you don't want the initial mount to animate.
5. Add reduced-motion fallbacks (useReducedMotion).

View Transitions and animateView

• Browser-native View Transitions (document.startViewTransition) have advanced: Chrome 147 (2026-03-27) added element-scoped, concurrent, and nested view transitions. When you need a large, layout-changing navigation transition that the browser can do cheaply, prefer the native API where available.

• Motion exposes an animateView() abstraction built on the View Transition API to simplify common patterns (shared-element transitions, crossfades, page effects) and add features like spring-based easing and interruption handling. animateView() is currently an alpha feature and part of Motion+ (Motion's paid/early access channel). See Motion's docs for details and examples.

• Pattern:

  • Detect native support: if (document.startViewTransition)
  • For production navigation-level transitions: prefer document.startViewTransition() or Motion's animateView() when you need View Transition semantics and are on supported browsers.
  • For component-level, gesture-driven, or nested shared-element transitions (fine-grained control), continue using Motion's layoutId and layout projection; the browser API may not reach inside deeply interactive components.

Example (native fallback):

if (document.startViewTransition) {
  document.startViewTransition(() => {
    navigate('/photo/42');
  });
} else {
  // Fall back to Motion-based route animation
}

Important: Motion's animateView() requires Motion+ access and is alpha — do not assume it's available in all projects. (Sources: motion.dev/docs/animate-view; motion.dev/changelog)

Decision tree

• Component enter/exit? → AnimatePresence + initial/animate/exit
• List with staggered items? → Variants with staggerChildren
• Element changes position/size? → layout prop (use layout="x"/"y" to lock axis when appropriate)
• Shared element across views? → layoutId
• Hover/tap/drag interaction? → Gesture props (whileHover, whileTap, whileDrag)
• Route or full-page transition and browser supports View Transitions? → Prefer native View Transitions or Motion's animateView() (Motion+ alpha); fallback to Motion when native support is absent or you need nested/interactive control
• Scroll-driven pinning or scrubbing? → NOT Motion — use GSAP ScrollTrigger

Edge cases and gotchas

1. Import path — Motion is published as the motion ecosystem. Import React bindings from motion/react (recommended). The legacy framer-motion package remains available for migration, but prefer motion.dev docs.

2. AnimatePresence requires keys — every direct child of AnimatePresence must have a unique key prop, or exit animations will not trigger.

3. layout + border-radius — layout animation can distort border-radius during interpolation. Use layout="position" if only position should animate.

4. Exit animations and React Strict Mode — Motion addressed many Strict Mode issues in March 2026 releases; test exit behavior in production builds. (See Motion changelog entries: 12.35.1–12.38.0.)

5. Spring oscillation — low damping values cause visible oscillation. For UI elements that should land cleanly, keep damping above ~15.

6. Server-side rendering — Motion components render their initial state on the server. Ensure initial values produce a usable static layout.

7. animateView / View Transitions — native View Transitions can be more efficient for large route-level changes. Chrome 147 added element-scoped and nested view transitions which make more complex nested transitions possible. Motion's animateView() wraps the browser API and adds features, but it is alpha and Motion+ gated — don't assume it is available in all projects.

8. Performance: Motion's March 2026 releases included memory and WAAPI improvements for layout animations. If you rely heavily on layout animations, upgrade to the latest patch in the 12.35–12.38 series (see changelog).

Examples

(Examples preserved — minimal edits to keep copy-pasteable code.)

Example 1 — Staggered list entrance

const listVariants = {
  hidden: {},
  visible: { transition: { staggerChildren: 0.06 } },
};

const itemVariants = {
  hidden: { opacity: 0, x: -12 },
  visible: { opacity: 1, x: 0, transition: { type: "spring", stiffness: 200, damping: 20 } },
};

function FeatureList({ features }: { features: string[] }) {
  return (
    <motion.ul variants={listVariants} initial="hidden" animate="visible">
      {features.map((f) => (
        <motion.li key={f} variants={itemVariants}>{f}</motion.li>
      ))}
    </motion.ul>
  );
}

Example 2 — Gesture-driven card

<motion.div
  whileHover={{ scale: 1.02, boxShadow: "0 8px 24px rgba(0,0,0,0.12)" }}
  whileTap={{ scale: 0.98 }}
  transition={{ type: "spring", stiffness: 300, damping: 25 }}
  className="cursor-pointer rounded-card bg-surface-elevated p-space-lg"
>
  <h3>Interactive card</h3>
</motion.div>

Example 3 — Page route transition

When the browser supports the View Transitions API (Chrome 147+ and other modern browsers), prefer it for full route/page transitions because the browser can perform large, concurrent layout changes more cheaply. For component-level shared-element transitions or interactive gestures, keep using Motion's layoutId and layout projection.

if (document.startViewTransition) {
  document.startViewTransition(() => {
    // perform navigation or DOM swap
    navigate('/photo/42');
  });
} else {
  // fallback to Motion-based route animation
}

Evaluation checklist

• Import from "motion/react" (recommended)
• useReducedMotion() checked and fallbacks provided
• Exit animations wrapped in <AnimatePresence> with keys
• Spring configs are tuned to match the interaction feel
• Enter animations are split into semantic chunks with stagger
• Exit animations are subtler than enter animations
• No competing animations on the same element
• Layout animations use layout="position" when only position should change
• Gesture interactions have visible hover/press feedback

Research references

• Motion changelog (Mar 2026): https://motion.dev/changelog — Motion 12.36.0 (2026-03-09) added axis-locked layouts and skipInitialAnimation; 12.37.0 & 12.38.0 (2026-03-16) added color-space support and layoutAnchor.
• Motion docs: React bindings and import path: https://motion.dev/docs/react
• Motion animateView docs (alpha, Motion+): https://motion.dev/docs/animate-view
• GitHub changelog (full): https://github.com/motiondivision/motion/blob/main/CHANGELOG.md
• Chrome Developer Blog: Chrome 147 view transitions (2026-03-27): https://developer.chrome.com/blog/element-scoped-view-transitions