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 }}
/>

(Install: npm install motion. Import React bindings from motion/react.)

Variants

Named animation states that propagate through component trees — use them for staggered entrances and shared state.

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>

Remember: every direct child of AnimatePresence needs a stable key for exit animations to run.

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 March 2026 patch series (refer to Motion changelog) added controls and fixes for layout projection, color spaces, and scroll-linked timelines. Notable changelog entries (Motion changelog):

• Motion 12.35.0 (Mar 3, 2026): Added ViewTimeline support for scroll and useScroll.
• Motion 12.35.1 / 12.35.2 (Mar 6–9, 2026): Multiple fixes — Strict Mode exit/interruption fixes, WAAPI final-style commits, percent-translate handling, and layout jump/rounding fixes.
• Motion 12.36.0 (Mar 9, 2026): Added axis-locked layout animations with layout="x" and layout="y", and added skipInitialAnimation to useSpring.
• Motion 12.37.0 (Mar 16, 2026): Added color-space support (oklch, oklab, lch, lab, color-mix, light/dark color types) and memory/layout improvements.
• Motion 12.38.0 (Mar 16, 2026): Added layoutAnchor for custom projection anchors; Reorder and AnimatePresence fixes for re-ordering/virtualized lists and exit clean-up.

If you rely on layout animations, upgrade to the March 2026 patch series for these controls and fixes (see Motion changelog).

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 (added in 12.36.0) 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) continue to evolve. Chrome added element-scoped and nested view transitions (Chrome 147) which make nested and concurrent transitions more capable. See Chrome Dev blog: https://developer.chrome.com/blog/element-scoped-view-transitions

• Motion exposes animateView() — a Motion convenience built on top of the browser View Transition API that adds spring easing, interruption handling, and shared-element helpers. Per Motion's docs, animateView() is currently in alpha and exclusive to Motion+ members (early access). See Motion's docs: https://motion.dev/docs/animate-view

Patterns and guidance:

• Feature-detect: if (document.startViewTransition) { /* prefer native or animateView */ }
• For large route-level transitions, prefer the native View Transition API where available — the browser can perform large layout swaps efficiently.
• Use Motion's animateView() only if you have Motion+ access and need Motion's additional helpers; it is early-access and gated.
• For component-level, gesture-driven, or highly interactive shared-element transitions, continue using layoutId and Motion's layout projection — the native API does not fully replace fine-grained interactive control yet.

Example (native fallback):

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

Important: Motion's animateView() is an early-access API behind Motion+; gate usage on feature detection and project access.

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 package. Import React bindings from motion/react (recommended). The legacy framer-motion package remains available but is not the recommended entry point for new projects.

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 the March 2026 patch series; test exit behavior in production builds and upgrade to the latest patch if you observe Strict Mode-only glitches (see changelog).

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 improve native capabilities. 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: The March 2026 patch series included memory, WAAPI, and layout improvements. If you rely heavily on layout animations, upgrade to the latest March 2026 patches (see https://motion.dev/changelog).

Examples

(Examples preserved — 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 docs (overview): https://motion.dev/docs — confirms install/import path and docs.
• animateView() docs (alpha, Motion+): https://motion.dev/docs/animate-view — notes animateView() is alpha and exclusive to Motion+ members.
• Motion changelog (Mar 3–Mar 16, 2026): https://motion.dev/changelog — authoritative list of 12.35.0 → 12.38.0 patch entries (ViewTimeline/useScroll, axis-locked layouts, skipInitialAnimation, color-space support, layoutAnchor, Strict Mode and memory fixes).
• GitHub repository and README: https://github.com/motiondivision/motion — confirms package name and usage examples (npm install motion, import { motion } from "motion/react").
• Chrome Developer Blog: Chrome 147 element-scoped view transitions (Mar 27, 2026): https://developer.chrome.com/blog/element-scoped-view-transitions

Summary

Practical, copy-pasteable guidance for Motion (formerly Framer Motion): install, import path, layout controls, March 2026 patch notes (12.35–12.38), and View Transitions / Motion+ animateView guidance.