Motion for React skill for Codex

Done well means: components animate from state, not imperative timing hacks; exits actually play; layout animations do not distort text; reduced-motion users get a calm version; and the animation code does not ship to routes that never use it.

Before writing anything

1. Read AGENTS.md and package.json. Note whether the project has framer-motion or motion, the React version, and whether it uses the Next.js App Router (server components).
2. Grep for existing patterns: rg "from \"(framer-motion|motion/react)\"" -n and any shared transition presets. Reuse them.
3. Installing or upgrading needs network: npm install motion (or the project’s package manager). In a Codex sandbox without network, ask for approval first.

Migrating from framer-motion

The API is the same; the package and import path changed.

npm uninstall framer-motion && npm install motion
rg -l "from ['\"]framer-motion['\"]" src | xargs sed -i '' "s#from ['\"]framer-motion['\"]#from \"motion/react\"#"

(sed -i '' is BSD/macOS; drop the '' on GNU.) Run the type checker afterwards; a few deprecated props from very old Framer Motion versions may surface.

Server components

motion.div uses hooks and must run on the client. In the Next.js App Router:

• Put animated UI in a file with "use client", or
• For a simple animated wrapper inside a server component, import import * as motion from "motion/react-client" and use <motion.div> there.

Never add "use client" to a layout or page just to animate one child; push the boundary down.

Pattern table

Goal	Tool
Fade/slide in on mount	initial + animate
Animate out before removal	AnimatePresence + exit
Swap one element for another (step wizard, tab panel)	AnimatePresence mode="wait" + changing key
Reorder lists, size changes	layout prop
Thumbnail grows into a modal	shared layoutId on both elements
Coordinated children	variants + delayChildren: stagger(...)
Hover / press feedback	whileHover, whileTap, whileFocus
Drag, swipe to dismiss	drag, dragConstraints, onDragEnd with velocity
Scroll-linked progress or parallax	useScroll + useTransform (+ useSpring)
Imperative sequence	useAnimate

Enter and exit

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

export function Toasts({ items }: { items: Toast[] }) {
  return (
    <ul>
      <AnimatePresence initial={false}>
        {items.map((t) => (
          <motion.li
            key={t.id}
            layout
            initial={{ opacity: 0, y: 12 }}
            animate={{ opacity: 1, y: 0 }}
            exit={{ opacity: 0, x: 40 }}
            transition={{ type: "spring", stiffness: 500, damping: 40 }}
          >
            {t.message}
          </motion.li>
        ))}
      </AnimatePresence>
    </ul>
  );
}

Exit rules that cause most “exit does not play” bugs:

• AnimatePresence must stay mounted; the conditional goes inside it, not around it.
• Each direct child needs a stable, unique key (never the array index for reorderable lists).
• The element with exit must be a direct child, or a custom component that renders a motion element and forwards its props.
• mode="wait" plays one exit before the next enter; mode="popLayout" removes the exiting element from layout flow immediately (pair it with layout on siblings, and the child must forward a ref).

Layout animations

<motion.div layout transition={{ layout: { duration: 0.25 } }}>
  <motion.h3 layout="position">{title}</motion.h3>
  {expanded && <p>{body}</p>}
</motion.div>

• Layout animation uses transforms, so children can look stretched. Put layout on children too, or layout="position" on text so only position animates.
• borderRadius and boxShadow are corrected automatically only when set via style or animated by Motion, not via a CSS class.
• Components that re-layout together but are not siblings need <LayoutGroup>.
• Scrollable ancestors need layoutScroll; position: fixed ancestors need layoutRoot.

Shared element:

{selected ? (
  <motion.div layoutId={`card-${selected.id}`} className="modal">...</motion.div>
) : (
  items.map((i) => <motion.div key={i.id} layoutId={`card-${i.id}`} onClick={() => select(i)} />)
)}

Wrap the swapping region in AnimatePresence when the old element should also fade.

Variants and stagger

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

const list = { hidden: {}, show: { transition: { delayChildren: stagger(0.05) } } };
const item = { hidden: { opacity: 0, y: 8 }, show: { opacity: 1, y: 0 } };

<motion.ul variants={list} initial="hidden" animate="show">
  {rows.map((r) => <motion.li key={r.id} variants={item}>{r.label}</motion.li>)}
</motion.ul>

Children inherit the variant label from the parent; do not set animate on them. Older code uses staggerChildren: 0.05, which still works.

Gestures and drag

<motion.div
  drag="x"
  dragConstraints={{ left: 0, right: 0 }}
  dragElastic={0.2}
  onDragEnd={(_, info) => {
    if (info.offset.x > 120 || info.velocity.x > 600) onDismiss();
  }}
  whileTap={{ scale: 0.98 }}
/>

• Drag must have a keyboard or button alternative (WCAG 2.5.7 Dragging Movements).
• whileHover does not fire on touch; never hide essential actions behind hover.

Scroll-linked values

const { scrollYProgress } = useScroll({ target: ref, offset: ["start end", "end start"] });
const y = useTransform(scrollYProgress, [0, 1], [40, -40]);
const smooth = useSpring(scrollYProgress, { stiffness: 120, damping: 30 });
return <motion.section ref={ref} style={{ y }} />;

Motion values update outside React render; do not mirror them into useState on every frame. Use useMotionValueEvent when something must react to a threshold.

Reduced motion and bundle size

import { LazyMotion, domAnimation, MotionConfig } from "motion/react";
import * as m from "motion/react-m";

export function Providers({ children }) {
  return (
    <MotionConfig reducedMotion="user">
      <LazyMotion features={domAnimation} strict>{children}</LazyMotion>
    </MotionConfig>
  );
}
// then use <m.div> instead of <motion.div>

• reducedMotion="user" disables transform and layout animations for users with the OS setting while keeping opacity and color. Use useReducedMotion() for custom branches (e.g. skip parallax).
• LazyMotion with m components cuts the initial bundle; use domMax instead of domAnimation only when you need layout animations or drag. strict throws if a full motion component sneaks in.

Gotchas

• Animating height: "auto" works, but combining it with layout on the same element fights; pick one.
• initial={false} on AnimatePresence skips enter animations on first paint, which avoids hydration flashes for server-rendered lists.
• Changing key remounts the subtree and resets its state; use it deliberately.
• A spring defined by stiffness/damping overrides duration; to think in time, use visualDuration + bounce instead. Do not mix the two styles in one transition.
• In tests (Jest/Vitest + jsdom) animations do not run; assert on the end state, or set MotionGlobalConfig.skipAnimations = true in setup.

Verification

• Type check and build pass; no framer-motion imports remain if migrating.
• Every exit plays: toggle each conditional and watch in the browser at slow speed (DevTools Animations panel does not show JS animations; use the Performance panel).
• Emulate prefers-reduced-motion: reduce and confirm transforms and layout motion stop.
• Check bundle impact with the project’s analyzer; routes without motion do not import it.
• Drag and hover interactions have keyboard equivalents.

Output

Report: components changed, which pattern each uses (presence, layout, layoutId, variants, gesture, scroll), reduced-motion behavior, and bundle effect if LazyMotion was introduced.