/web-animation-framer-motion

name: web-animation-framer-motion
description: Motion (formerly Framer Motion) patterns - motion components, variants, AnimatePresence, gestures, layout animations, scroll-linked motion, reduced-motion handling

Motion Animation Patterns

> **Quick Guide:** `motion.*` components take `initial`, `animate`, `exit` and `transition` props; > variants lift those states into named sets a parent can orchestrate; `AnimatePresence` is what > keeps a removed component mounted long enough to animate out; `layout` and `layoutId` run FLIP > animations over layout changes; `useScroll` and `useInView` drive motion from scroll position. > Animate `x`, `y`, `scale`, `rotate` and `opacity`, and set `MotionConfig reducedMotion="user"` at > the root.

> **Import:** `import { motion } from "motion/react"` — the package was renamed from `framer-motion` > at v11.

**Detailed Resources:**

• [examples/core.md](examples/core.md) — motion components, variants, AnimatePresence, gestures, reduced motion
• [examples/layout.md](examples/layout.md) — `layout`, `layoutId`, expandable cards, tab indicators
• [examples/scroll.md](examples/scroll.md) — scroll progress, reveal on view, parallax
• [examples/sequences.md](examples/sequences.md) — `useAnimation` chains, keyframe arrays, `stagger()` shaping
• [examples/svg.md](examples/svg.md) — `pathLength` drawing effects
• [reference.md](reference.md) — v11/v12 migration, transition presets, prop and hook tables

---

Which path applies

• **The element enters or leaves the React tree** — the animation needs `AnimatePresence` around it

and a `key` on it; follow [examples/core.md](examples/core.md).

• **The element stays mounted while its size or position changes** — `layout` measures before and

after and animates the difference; follow [examples/layout.md](examples/layout.md).

• **The same element appears in two places at different times** — a shared `layoutId` makes one

travel into the other; follow [examples/layout.md](examples/layout.md).

• **Scroll position drives the value** — `useScroll` with `useTransform`, or `whileInView` for a

one-shot trigger; follow [examples/scroll.md](examples/scroll.md).

• **Something outside React state triggers the animation** — a timer, a response, an error — then

`useAnimation` gives the imperative handle; follow [examples/sequences.md](examples/sequences.md).

---

<critical_requirements>

Before writing Motion code

**Wrap anything that animates on removal in `AnimatePresence`.** React unmounts the node the instant its condition goes false, so `exit` has nothing left to run against without the wrapper holding the node in the tree until the animation finishes.

**Give every direct child of `AnimatePresence` a stable, unique `key`.** The key is what `AnimatePresence` matches the departing element against; an index key re-points to a different item when the list changes and animates the wrong element out.

**Animate `x`, `y`, `scale`, `rotate` and `opacity`.** Motion writes these to `transform` and `opacity`, which the compositor owns; `height`, `width` and `marginTop` re-run layout on each frame instead.

**Set `MotionConfig reducedMotion="user"` at the app root.** Transform and layout animations then disable themselves for users who asked their OS for reduced motion, while opacity and colour keep working — so state changes stay legible rather than becoming instant.

</critical_requirements>

---

**Auto-detection:** motion/react, framer-motion, motion.div, AnimatePresence, MotionConfig, LayoutGroup, LazyMotion, layoutId, whileHover, whileTap, whileDrag, whileInView, useAnimation, useScroll, useTransform, useMotionValue, useSpring, useInView, usePageInView, useReducedMotion, useDragControls, staggerChildren, delayChildren, Variants

**Applies to:**

• Enter, exit and presence animation tied to React's mount lifecycle
• Orchestrating several elements from one parent with variants and stagger
• Gesture-driven motion — hover, tap, drag, focus
• Scroll-triggered and scroll-linked effects
• Layout changes and shared-element transitions between containers
• Imperative sequences fired by events React state does not model

**Handled elsewhere:**

• Purely declarative state feedback — a hover colour, a focus ring — where nothing mounts, unmounts

or moves. The styling layer settles those without a component wrapper

• Frame-level timeline authoring, where the deliverable is a scrubbable timeline rather than a set of

component states

• Whole-document view swaps where the browser composites an outgoing and incoming page together

---

<philosophy>

Motion animates state rather than time. A component declares what it looks like in each state, and Motion works out the interpolation, the interruption and the velocity carried across it — which is why a spring interrupted mid-flight continues from where it was rather than restarting.

</philosophy>

---

<decision_framework>

When Motion earns its place

Motion is worth the component wrapper and the bundle when at least one is true:

• The element is being **removed** from the tree and must animate before it goes
• The **from** value is measured rather than authored — a layout change, a drag release, an

interrupted spring

• Several elements must be **orchestrated** from one trigger, with stagger and reverse-on-exit
• The animated value is **derived from a continuous input** such as scroll progress

None of those true means the motion is a state change with both ends known in advance, which needs no runtime.

Variants or direct props

Reach for variants once more than one element shares the animation, or once the parent needs to control child timing — `staggerChildren` and `delayChildren` only exist on the variant path, and children inherit the parent's variant name without being passed anything. A single element with two states is clearer with `initial`/`animate` written inline.

</decision_framework>

---

<patterns>

Core patterns

Pattern 1: Motion Components