Nextjs Framer Motion Animations

Next.js + Motion/Framer Motion

Mission

Build small, purposeful, accessible animations in Next.js using Motion for React (the current package) or legacy framer-motion, without breaking server/client boundaries, performance, or usability.

Use this skill for

• First-render reveals and section entrances
• Hover, tap, and focus feedback on buttons, links, cards, tabs, and navigation
• Scroll-triggered reveals and modest scroll-linked effects
• Modals, drawers, dropdowns, accordions, tabs, and other enter/exit UI
• Layout and shared-element transitions with layout and layoutId
• Reorderable lists and light route-content transitions
• Debugging Motion behaviour in Next.js

Do not use this skill for

• GSAP-style timelines or cinematic sequences
• Canvas, WebGL, Three.js, or Lottie-led animation systems
• Heavy parallax or scroll-jacking storytelling
• Large creative-direction rewrites
• Pure CSS effects that do not justify client JavaScript, unless Motion is explicitly requested

Non-negotiables

• Prefer the lightest Motion API that solves the task.
• Preserve repo consistency. Do not mix motion and framer-motion imports in the same diff unless the task is an explicit migration.
• Keep animated logic in the smallest possible Client Component boundary.
• Respect reduced motion globally with MotionConfig reducedMotion="user" and locally with useReducedMotion() when behaviour must change.
• Prefer reusable primitives, variants, and motion tokens over repeated inline animation objects.
• Do not add a global provider, root-layout Client Component, or route-wide animation system unless the request genuinely needs it.

Default workflow

1) Audit the codebase first

Inspect:

• Router type: app/, pages/, or both.
• Current package: motion, framer-motion, or neither.
• Existing animation patterns and design-system components.
• Candidate transition boundaries: app/layout.tsx, app/template.tsx, pages/_app.tsx, shared UI shells.
• Whether the change is local animation, mount/unmount animation, layout animation, shared-element animation, reorder, or scroll-linked animation.

If shell access is available, run:

node scripts/audit-nextjs-motion.mjs --root /path/to/repo
node scripts/inspect-motion-target.mjs path/to/target-file.tsx --root /path/to/repo
node scripts/plan-motion-change.mjs --root /path/to/repo --target path/to/target-file.tsx --task "user request"

For broad skill iteration or repo-health checks, also run:

node scripts/check-motion-antipatterns.mjs --root /path/to/repo

2) Choose a package strategy

Default rules:

• New work or modernised motion layer: prefer the current motion package with imports from motion/react.
• Existing repo already on `framer-motion`: stay consistent unless the task explicitly includes migration.
• Passive App Router component with no hooks or client-only logic: motion/react-client can be appropriate, but it is an exception, not the default.
• Leaf animations with hooks, route state, presence, reorder, or interactivity: use a small Client Component boundary.

See references/MIGRATION.md and references/DECISION_TREE.md.

3) Choose the lightest correct API

Use this decision rule:

• Simple local animation: motion.*
• Bundle-sensitive shared shell: m.* with LazyMotion
• Repeated parent/child orchestration: variants plus stagger
• Mount/unmount or route exits: AnimatePresence
• Layout changes from React re-render: layout
• Shared-element transition: layoutId
• Sibling layout coordination or namespaced shared layout IDs: LayoutGroup
• Simple scroll reveal: whileInView
• Scroll-linked progress or parallax: useScroll plus motion values
• Imperative sequence or external trigger: useAnimate
• Design-system component wrapper: motion.create() with ref forwarding

See references/EXPERT_PLAYBOOK.md and references/DECISION_TREE.md.

4) Wire it correctly for the router

App Router

• Passive, hook-free animation in a server-friendly file: consider motion/react-client.
• Interactive or hook-driven UI: create a small Client Component leaf and keep data fetching server-side.
• Client wrapper around server-rendered children: useful for modal shells, drawers, and local visibility wrappers.
• Route enter/exit choreography: mount a persistent Client shell from a layout so AnimatePresence stays mounted.
• Segment replay on navigation: template.tsx is useful when you want remount semantics at a specific segment boundary.

See references/APP_ROUTER.md.

Pages Router

• Keep AnimatePresence stable in pages/_app.tsx for route transitions.
• Key routed children by a stable value that changes when you actually want a transition. For dynamic routes, router.asPath is usually safer than router.route.
• Do not rewrite _app.tsx for a one-off local animation.

See references/PAGES_ROUTER.md.

5) Apply the motion budget

Default ranges unless the user or design system says otherwise:

• Micro-interactions: 0.12s to 0.22s, scale no larger than 1.03, travel no more than 4px.
• Reveal / list entrance: 0.18s to 0.35s, travel 8px to 24px.
• Page / route transition: 0.22s to 0.45s, mostly opacity plus small Y translation.
• Layout animation: prefer Motion springs or layout; do not fake these with large manual transforms.

See references/EXPERT_PLAYBOOK.md and references/PERFORMANCE.md.

6) Validate before finishing

Always check:

• No server/client boundary mistakes
• Reduced motion works
• Focus is preserved for interactive UI
• No unnecessary layout shift or stretched content
• No duplicate or conflicting route wrappers
• Project still builds

Run repo checks when available:

npm run lint
npm run build

For repo audits or skill iteration, also run:

node scripts/check-motion-antipatterns.mjs --root /path/to/repo

Use references/CHECKLIST.md before finalising. When improving the skill itself, use references/EVALUATION.md and node scripts/run-evaluation-pack.mjs.

Implementation rules

• Prefer animating transform and opacity. Avoid animating top, left, large filters, and large shadows on big surfaces.
• When possible, turn the existing root element into a Motion element instead of adding a new wrapper. Extra wrappers often break layout, refs, selectors, or spacing.
• If using m plus LazyMotion, use:
• domAnimation for standard animations, variants, exit, hover, tap, and focus.
• domMax only when you need layout animations or drag/pan.
• Use AnimatePresence initial={false} for app-level wrappers unless first-load animation is explicitly desired.
• Use AnimatePresence mode="wait" only when a single child should fully exit before the next enters.
• Never key exit-sensitive children by array index.
• Start with layout before manual height choreography. If content stretches, add layout to the affected children or switch to layout="position" for aspect-ratio changes.
• If the scroll container is not the window, configure viewport.root or use useInView with the correct root.
• When animating next/image or image wrappers, preserve the layout box and animate transform or opacity rather than intrinsic size.
• When wrapping design-system components, call motion.create() outside render and make sure the wrapped component forwards its ref.
• If the user did not explicitly ask for Motion and the effect is just a tiny hover or focus style on a static server-rendered element, CSS may be the cleaner answer.

Scripts

• scripts/audit-nextjs-motion.mjs - inspects a repo, ranks likely target files, and emits JSON recommendations.
• scripts/inspect-motion-target.mjs - inspects one file and recommends boundary, import path, risks, and likely pattern fit.
• scripts/plan-motion-change.mjs - combines repo audit, target inspection, and task wording into a structured expert plan.
• scripts/check-motion-antipatterns.mjs - scans a repo for common Motion and Framer Motion anti-patterns and emits JSON findings.
• scripts/run-evaluation-pack.mjs - runs the bundled fixture-and-golden evaluation pack for skill iteration.
• scripts/scaffold-motion-primitives.mjs - copies template components from assets/ into a target directory, with optional import rewriting for legacy framer-motion.

Reference map

• references/EXPERT_PLAYBOOK.md - API selection, heuristics, motion tokens, anti-patterns
• references/DECISION_TREE.md - fast pattern and boundary selection
• references/APP_ROUTER.md - App Router boundaries, route shells, template.tsx, and server-friendly patterns
• references/PAGES_ROUTER.md - _app.tsx, keys, dynamic route nuances
• references/RECIPES.md - copy/paste implementations
• references/PERFORMANCE.md - bundle size, LazyMotion, layout and scroll performance
• references/ACCESSIBILITY.md - reduced motion, focus, modal guidance
• references/MIGRATION.md - framer-motion to motion package strategy
• references/TROUBLESHOOTING.md - failure modes and fixes
• references/CHECKLIST.md - final review before finishing
• references/EVALUATION.md - trigger tests, scenario fixtures, anti-pattern scans, and golden-output review

Output expectations

When modifying a repo, finish with: 1. The files changed 2. The Motion API and pattern chosen 3. Boundary strategy and package migration decision, if any 4. Reduced-motion handling 5. Performance or bundle-size choices, if relevant 6. Manual validation notes or commands run 7. Any caveats the developer should know

Typical request mapping

• "Make this button feel better" -> micro-interaction recipe
• "Animate cards in on scroll" -> reveal recipe; variants if staggered
• "Add a smooth route transition in App Router" -> persistent layout-mounted shell or content wrapper, not a root rewrite by default
• "Animate this accordion or tab underline" -> layout / layoutId / LayoutGroup
• "Make this drag list reorder smoothly" -> Reorder.Group / Reorder.Item
• "This breaks in App Router" -> inspect boundary and import path before editing
• "Modernise our Framer Motion setup" -> audit first, then use references/MIGRATION.md

Golden summary

The audit should flag, at minimum:

• mixed motion and framer-motion imports
• a client root App Router layout
• server files importing client-only Motion paths
• index keys under AnimatePresence
• transform-avoidant top / left animation
• repeated layoutId usage without LayoutGroup id
• motion.create() inside render
• motion/react-client used in a client-driven file
• Reorder.Item without Reorder.Group

Golden summary

• Change components/settings-drawer.tsx
• Keep the work in the existing client component
• Use AnimatePresence from motion/react
• Animate overlay and panel separately
• Mention stable keys, exit handling, and reduced-motion fallback

Golden summary

• Change components/product-card.tsx
• Keep the component server-friendly in App Router
• Prefer motion/react-client
• Use a small mount reveal on the existing root element
• Mention reduced motion and verify no unnecessary use client boundary was added

Golden summary

• Do not mark app/layout.tsx as a client component
• Create a small client route-transition shell rendered from app/layout.tsx
• Use AnimatePresence initial={false} keyed by pathname
• Keep transitions lightweight and route-content scoped

Golden summary

• Change components/ui/button.tsx
• Use motion.create() outside render
• Preserve ref forwarding
• Add restrained whileHover, whileTap, and whileFocus states
• Avoid wrapper divs

Golden summary

• Keep the repo on framer-motion
• Edit pages/_app.tsx
• Use AnimatePresence around the routed component
• Key by router.asPath when dynamic param changes should animate
• Keep the transition gentle and avoid architecture churn

Golden summary

• Change components/settings-tabs.tsx
• Use LayoutGroup plus layoutId
• Namespace repeated tab groups with LayoutGroup id
• Keep the change inside the existing client component

Accessibility guide

Reduced motion is mandatory

Default every animated subtree to:

<MotionConfig reducedMotion="user">
  {children}
</MotionConfig>

This automatically disables transform and layout animations while keeping non-spatial feedback like opacity and colour changes.

Custom reduced-motion behaviour

Use useReducedMotion() when the animation logic itself should change.

Typical adjustments:

• Replace x and y transitions with opacity changes
• Disable parallax and scroll-linked movement
• Disable autoplaying decorative video or background motion
• Shorten or remove sequential choreography

"use client";

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

export function Drawer({ open }: { open: boolean }) {
  const reduce = useReducedMotion();

  return (
    <motion.aside
      animate={{
        opacity: open ? 1 : 0,
        x: reduce ? 0 : open ? 0 : "100%",
      }}
    />
  );
}

Focus and keyboard use

Animation must not interfere with focus order or visible focus styles.

Rules:

• Keep CSS focus outlines or rings visible on animated buttons and links
• When content mounts or unmounts, do not lose the user's current focus target unexpectedly
• For dialogs, drawers, and popovers, let an accessibility-focused component library manage focus trapping and restoration

Motion should animate the surface, not own accessibility semantics.

Readability

Avoid:

• large parallax movement on text
• repeated fade-in or shimmer on copy the user is trying to read
• motion that hides where content moved to

Prefer:

• short structural transitions
• small positional cues
• opacity or colour changes instead of large spatial movement in reduced-motion mode

Accessibility review checklist

• Reduced motion enabled in OS: the UI still works and remains understandable
• Keyboard navigation still reaches every control
• Focus ring remains visible during hover, tap, and press states
• Modals and drawers restore focus on close
• Scroll-linked motion has a meaningful reduced-motion fallback

App Router guide

Mental model

In App Router, layouts and pages are Server Components by default. Treat Motion as a local concern unless the user clearly needs a broader transition system.

General rules:

• Keep data fetching and server-only logic in server components.
• Push Motion to the smallest leaf that actually needs it.
• Pass only serialisable props into client components.
• Avoid turning app/layout.tsx into a Client Component just to animate one hero, card, or modal.

Pattern 1: passive Motion component with motion/react-client

Use this only when all of the following are true:

• the repo uses the modern motion package
• the animation is passive and hook-free
• you do not need AnimatePresence, route hooks, scroll state, or local interactivity

Example:

import * as motion from "motion/react-client"

export function MotionCard({
  children,
  className,
}: {
  children: React.ReactNode
  className?: string
}) {
  return (
    <motion.article
      className={className}
      initial={{ opacity: 0, y: 8 }}
      animate={{ opacity: 1, y: 0 }}
      transition={{ duration: 0.25 }}
    >
      {children}
    </motion.article>
  )
}

Pattern 2: server parent, animated client leaf

Use when the animated part needs hooks, local state, or other client-only behaviour.

Good fit:

• useReducedMotion
• AnimatePresence
• whileInView with custom logic
• usePathname
• useScroll
• drag or reorder
• any component already using client hooks

Server component:

import { AnimatedHero } from "./animated-hero"

export default async function Page() {
  const data = await getData()

  return <AnimatedHero title={data.title} subtitle={data.subtitle} />
}

Client leaf:

"use client"

import { motion, useReducedMotion } from "motion/react"

export function AnimatedHero({
  title,
  subtitle,
}: {
  title: string
  subtitle: string
}) {
  const reduceMotion = useReducedMotion()

  return (
    <motion.section
      initial={reduceMotion ? { opacity: 0 } : { opacity: 0, y: 12 }}
      animate={{ opacity: 1, y: 0 }}
      transition={{ duration: 0.3 }}
    >
      <h1>{title}</h1>
      <p>{subtitle}</p>
    </motion.section>
  )
}

Pattern 3: client wrapper around server-rendered children

Use when the wrapper needs Motion but the inner content can stay server-rendered.

Good fit:

• modal shell
• drawer shell
• animated panel open/close
• local route-content wrappers
• visibility wrappers around server-rendered content

"use client"

import { AnimatePresence, motion } from "motion/react"

export function AnimatedShell({
  open,
  children,
}: {
  open: boolean
  children: React.ReactNode
}) {
  return (
    <AnimatePresence>
      {open ? (
        <motion.div
          key="shell"
          initial={{ opacity: 0, y: 8 }}
          animate={{ opacity: 1, y: 0 }}
          exit={{ opacity: 0, y: 8 }}
        >
          {children}
        </motion.div>
      ) : null}
    </AnimatePresence>
  )
}

Pattern 4: persistent route shell for enter and exit choreography

Use when the user genuinely wants route-content transitions and the presence boundary must survive route changes.

Recommended structure

• Keep app/layout.tsx as the stable server layout.
• Render a small Client Component shell inside it.
• Put AnimatePresence in that shell and key the routed content inside it.

Example app/layout.tsx

import type { ReactNode } from "react"
import { RouteTransitionShell } from "@/components/motion/route-transition-shell"

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        <RouteTransitionShell>{children}</RouteTransitionShell>
      </body>
    </html>
  )
}

Pattern 5: segment replay with template.tsx

Use template.tsx when you want remount semantics at a specific segment boundary. It is useful for replaying enter animations, but it is not a complete substitute for a persistent exit-aware shell.

Example app/template.tsx

import { FadeInOnMount } from "@/components/motion/fade-in-on-mount"

export default function Template({ children }: { children: React.ReactNode }) {
  return <FadeInOnMount>{children}</FadeInOnMount>
}

Choosing the right pattern

• Choose Pattern 1 for passive, hook-free motion in modern Motion codebases.
• Choose Pattern 2 when the animated part needs client hooks or local state.
• Choose Pattern 3 when a thin wrapper can stay client-side while the inner content remains server-rendered.
• Choose Pattern 4 when route enter and exit choreography actually matters.
• Choose Pattern 5 when remount-on-navigation semantics are enough.

Common mistakes

• Marking the root layout as client for a one-off animation
• Passing functions from a server component into a client animation leaf
• Importing framer-motion directly into an App Router server file
• Replacing a server-rendered subtree with a large client rewrite just to animate one element
• Adding AnimatePresence everywhere “just in case”

Final review checklist

Run this before finishing.

Scope

• The diff solves the specific request
• No unnecessary global animation architecture was introduced
• The chosen pattern is the narrowest correct one

Package and imports

• Import path matches the repository choice
• motion and framer-motion are not mixed casually
• motion/react-client is only used in motion package codebases
• Any LazyMotion setup uses the correct feature pack

Next.js architecture

• App Router server components stay server-side where possible
• Any Motion hook usage lives in a Client Component
• Client boundaries are intentionally small
• Props passed into client components are serialisable
• Route-transition wrappers stay mounted if exit animations are required

Pattern correctness

• Reveal uses local initial and animate
• Scroll reveal uses whileInView unless state is required
• Stagger timing lives on the parent
• Exit animation uses AnimatePresence with direct-child stable keys
• Layout animation uses layout before bespoke size choreography
• Shared elements use layoutId, and repeated widgets use LayoutGroup id if needed
• Reorder uses Reorder.Group and Reorder.Item

Accessibility

• Reduced motion has been handled thoughtfully
• Hover-only cues also have keyboard or focus parity where relevant
• Focus management and click targets still work
• Important information is not hidden behind slow animation

Performance

• The chosen boundary does not pull a large subtree into the client without reason
• The route is not paying for a global provider unnecessarily
• If a heavy subtree was introduced, bundle impact was considered
• Images still reserve layout space
• Observer or wrapper count has not grown without need

Verification

• Relevant lint, typecheck, test, or build checks ran if available
• No obvious hydration mismatch risk remains
• Visual behaviour was sanity-checked in the affected UI
• Final answer names changed files, pattern choice, import path, and tuning knobs

Skill iteration

• If you changed the skill itself, run node scripts/run-evaluation-pack.mjs
• Review trigger coverage in assets/evaluation-pack/trigger-tests.json
• Recheck anti-pattern guidance with node scripts/check-motion-antipatterns.mjs --root /path/to/repo

Decision tree

Use this to choose the narrowest correct pattern before editing.

Boundary choice shortcut

Use motion/react-client when

• the repo uses the modern motion package
• the file can stay server-friendly
• the animation is passive and hook-free
• you do not need AnimatePresence, route hooks, useScroll, useAnimate, or local interactive state

Use a small Client Component leaf when

• you need useReducedMotion, useInView, useScroll, useAnimate, or route hooks
• you need AnimatePresence
• the component is already interactive or stateful
• the animation is local to one widget and should not drag a larger subtree into the client

Use a client wrapper around server-rendered children when

• the wrapper controls visibility or transition
• the wrapped content can stay server-rendered
• the boundary is smaller than converting the whole parent to a Client Component

Use a layout-mounted shell or pages/_app.tsx wrapper when

• you genuinely need route-content enter and exit choreography
• the transition should survive route changes because the presence boundary stays mounted

Choosing between closely related APIs

whileInView vs useInView

• Start with whileInView for straightforward reveal-on-scroll.
• Use useInView when entering the viewport must drive React state, imperative code, or cross-element coordination.
• If the scroll container is not the window, make sure the correct root is configured.

layout vs manual height animation

• Start with layout for accordions, chips, tab underlines, and small reflows.
• Reach for manual height or useAnimate only when layout cannot model the transition cleanly.
• If content stretches during layout animation, try layout="position" or add layout to the affected children.

Variants vs useAnimate

• Use variants for ordinary parent-child orchestration, stagger, and reusable patterns.
• Use useAnimate for small imperative sequences or when declarative variants become awkward.
• Do not escalate to a timeline mindset for simple UI state changes.

motion vs m plus LazyMotion

• Use plain motion for local edits and small numbers of animated elements.
• Use m plus LazyMotion when Motion becomes broad in scope or bundle size is a real concern.
• Prefer domAnimation unless you truly need layout or drag features that require domMax.

If the request says “make it smoother”

• Reduce travel distance before increasing duration.
• Prefer opacity plus a small y change over bigger movement.
• Remove unnecessary bounce from content surfaces.
• Try layout before manual size choreography.
• Avoid stacking reveal, scale, rotate, and parallax on the same region.

If the request says “this breaks in App Router”

Check, in order: 1. Is a server file importing motion/react or framer-motion directly? 2. Does the file actually need hooks or can it stay passive with motion/react-client? 3. Can the animation move into a smaller client leaf instead of making the parent or layout client-side? 4. Are only serialisable props being passed into the client component? 5. Is the presence boundary staying mounted if exit animations are expected?

If bundle size suddenly matters

• Prefer CSS for tiny hover or focus effects when Motion is not a requirement.
• Keep Client Component boundaries small.
• Consider LazyMotion for large motion-heavy subtrees.
• Lazy-load animation-heavy islands such as rarely opened drawers or modals.
• Inspect actual import paths before assuming the problem is Motion itself.

Evaluation pack

Use this when you are improving the skill itself, reviewing a repo before broad edits, or checking whether your Motion guidance is still "expert" rather than merely plausible.

What the pack tests

The pack is split into three layers:

1. Trigger coverage

• assets/evaluation-pack/trigger-tests.json
• Positive prompts that should load the skill
• Negative prompts that should not

2. Scenario fixtures + golden decisions

• assets/evaluation-pack/fixtures/
• assets/evaluation-pack/goldens/
• Small repos that represent the most failure-prone decisions:
• passive App Router reveal
• client-side presence UI
• App Router route shell
• Pages Router legacy route transitions
• shared-layout tabs
• design-system wrapper work

3. Anti-pattern detection

• scripts/check-motion-antipatterns.mjs
• Static checks for common mistakes such as:
• mixed motion / framer-motion
• server files importing client-only Motion paths
• root layout widened to client without cause
• index keys under AnimatePresence
• top / left animation instead of transforms
• repeated layoutId without LayoutGroup id
• motion.create() inside render

Scripts

Scenario-aware planner

Use this before non-trivial edits:

node scripts/plan-motion-change.mjs --root /path/to/repo --target path/to/file.tsx --task "Add a subtle route transition"

It combines repo audit + target inspection + task wording, then returns JSON with:

• package strategy
• import-path choice
• boundary choice
• recommended pattern
• first steps
• reduced-motion plan
• performance plan
• validation checklist

Anti-pattern scan

node scripts/check-motion-antipatterns.mjs --root /path/to/repo

Returns JSON with repo-level warnings and file-level issues.

Full evaluation pack

node scripts/run-evaluation-pack.mjs
node scripts/run-evaluation-pack.mjs --case app-router-route-shell
node scripts/run-evaluation-pack.mjs --list

The evaluator runs the planner or anti-pattern scanner against the bundled fixtures and compares the result to the corresponding golden JSON.

Expert bar

Treat the skill as "expert" only when all of these are true:

• It chooses the repo's existing package strategy unless migration is explicit.
• It keeps the Client Component boundary as small as possible.
• It distinguishes App Router route shells from template.tsx replay semantics.
• It treats AnimatePresence, layoutId, LayoutGroup id, and motion.create() as correctness-sensitive APIs.
• It accounts for reduced motion instead of treating it as optional polish.
• It explains validation, not just implementation.

Manual review prompts

Use these when reviewing agent output:

• Did the answer keep the change local?
• Did it pick the right import path for the repo?
• Did it choose the correct Next.js boundary?
• Did it mention reduced motion?
• Did it avoid route-transition overreach?
• Did it call out likely failure modes before they happen?
• Did it describe how to validate the change?

Output contract

See assets/evaluation-pack/output-contract.json.

The final answer should usually name:

• files changed or files likely to change
• chosen Motion API / pattern
• boundary strategy
• package decision
• reduced-motion handling
• performance considerations
• validation notes
• caveats

Expert playbook

Package strategy

Use one package strategy per diff:

• Current default: motion
• Legacy compatibility: framer-motion
• Do not mix both in the same patch unless the task is an explicit migration.

Use the current package when:

• Installing animation support from scratch
• Touching many imports anyway
• Building a new shared motion layer

Stay on legacy framer-motion when:

• The repo already uses it heavily
• The task is small and package churn would dominate the diff
• The user asked for the smallest possible change

API selection matrix

Motion tokens

Start here before tuning.

Easing

Use one default easing curve across the feature:

const easeOut = [0.22, 1, 0.36, 1] as const

Micro-interactions

const microTransition = { duration: 0.16, ease: easeOut }

Reveal / entrance

const revealTransition = { duration: 0.28, ease: easeOut }

Springs

Use springs when the UI is reacting to stateful layout changes rather than decorative fades.

const gentleSpring = { type: "spring", stiffness: 260, damping: 24, mass: 0.9 } as const
const snappySpring = { type: "spring", stiffness: 420, damping: 32, mass: 0.7 } as const

Guideline:

• Use tween for simple opacity and transform reveals.
• Use spring for toggles, expanding panels, and layout-driven movement.
• Use visualDuration only when you need a spring to visually line up with time-based transitions.

Strong opinions

• Default to subtle motion. Most UIs improve with less movement, not more.
• Use one primary animation idea per surface. Do not layer hover scale, shadow bloom, blur, and parallax onto the same component unless the user explicitly wants it.
• Choose layout animation instead of manual height or position hacks when the movement is caused by a React re-render.
• Choose shared layout instead of manually syncing coordinates for tabs, pills, and selected cards.
• Choose imperative sequencing only when declarative props become harder to reason about.

Route transition rules

• If you need exit animations, AnimatePresence must stay mounted while the child changes.
• In App Router, prefer a persistent client shell under a layout for exit choreography.
• Use template.tsx when you want segment remount semantics and replayed enter animations, not as the only tool for all route exits.
• In Pages Router, keep presence in _app.tsx.
• For dynamic routes in Pages Router, router.route will not change across param changes. Use router.asPath when those changes should animate.

Layout animation rules

• If content looks stretched, add layout to the affected children too.
• If an image or text block changes aspect ratio, prefer layout="position" so only position animates.
• If you reuse the same layoutId in multiple repeated groups, namespace them with LayoutGroup id.
• When mixing exiting children and layout animation, be ready to wrap related elements in LayoutGroup.

Scroll rules

• Reveal and scroll-linked animation are different tasks. Use whileInView for reveal, useScroll for scroll-linked values.
• Avoid parallax on long text blocks.
• For progress bars, map scrollYProgress through useSpring so the bar feels smooth rather than noisy.

Accessibility rules

• Every animated subtree should either inherit MotionConfig reducedMotion="user" or explicitly honour useReducedMotion().
• Reduced motion does not mean zero feedback. Prefer opacity or colour changes over large transforms.
• For modals and drawers, let a dialog library own focus management. Motion should own visuals.

Anti-patterns

• Mixing motion and framer-motion imports
• Mounting and unmounting AnimatePresence itself
• Keying exit-sensitive nodes by array index
• Using top and left when x and y would do
• Animating huge shadows or blurs on large surfaces
• Calling motion.create() inside render
• Reusing global layoutId values across multiple independent tab sets
• Treating template.tsx as if it remounts on search-param-only changes

Migration guide

Current package naming

Motion for React is now published as the motion package.

Preferred install:

npm install motion

Preferred imports:

import { motion } from "motion/react"

Legacy framer-motion

Many repos still use framer-motion. That is fine if the task is small and you want the minimum diff.

Stay vs migrate

Stay on legacy framer-motion when:

• The repo already uses it
• The change touches only a few files
• The user wants a minimal patch

Migrate to motion when:

• You are installing Motion from scratch
• You are already touching many imports
• You want the current package naming and docs alignment
• You are building a fresh motion layer or shared primitives library

Minimal migration steps

npm uninstall framer-motion
npm install motion

Then swap imports:

// before
import { motion, AnimatePresence } from "framer-motion"

// after
import { motion, AnimatePresence } from "motion/react"

Important migration rules

• Migrate in one focused diff if possible.
• Do not leave a codebase half on framer-motion and half on motion.
• If the codebase uses m plus LazyMotion, the modern imports are:
• import * as m from "motion/react-m"
• import { LazyMotion, domAnimation, domMax } from "motion/react"

App Router note

Motion docs also provide:

import * as motion from "motion/react-client"

Use that only when you explicitly need Motion components from a Server Component context. Most animation logic should still live in Client Components.

Older APIs you may see

If you encounter older shared-layout code:

• Replace AnimateSharedLayout patterns with layoutId
• Use LayoutGroup when multiple components affect each other's layout or when repeated shared-layout groups need namespacing

Suggested migration sequence

1. Run the audit script 2. Decide whether this task is a small local patch or an explicit migration 3. If migrating, update package and imports first 4. Run the build before changing animation behaviour 5. Then refactor patterns, wrappers, and recipes

Pages Router guide

Core pattern

In Pages Router, the most reliable route-transition setup is a stable AnimatePresence in pages/_app.tsx and an animated page wrapper inside each page or shared layout.

_app.tsx wiring

Keep the presence wrapper mounted at the app root.

import type { AppProps } from "next/app";
import { AnimatePresence, MotionConfig } from "motion/react";

export default function App({ Component, pageProps, router }: AppProps) {
  return (
    <MotionConfig reducedMotion="user">
      <AnimatePresence initial={false} mode="wait">
        <Component {...pageProps} key={router.asPath} />
      </AnimatePresence>
    </MotionConfig>
  );
}

See assets/pages-app.tsx.

Which key to use

Choose the key based on what should count as a new page:

• router.asPath
• Best when dynamic param changes should animate
• Includes query string and hash, so query-only changes can also retrigger transitions

• router.route
• Stable route pattern like /posts/[slug]
• Good when you only want transitions between different route templates
• Not enough when /posts/a and /posts/b should animate differently

Rule of thumb:

• Start with router.asPath
• If query-string transitions become noisy, switch to a path-only key derived from router.asPath.split("?")[0]

Page wrapper

A page still needs its own animated surface.

import { motion } from "motion/react";

export default function Page() {
  return (
    <motion.main
      initial={{ opacity: 0, y: 12 }}
      animate={{ opacity: 1, y: 0 }}
      exit={{ opacity: 0, y: -8 }}
      transition={{ duration: 0.28, ease: [0.22, 1, 0.36, 1] }}
    >
      ...
    </motion.main>
  );
}

Navigation notes

Prefer Next.js <Link> for navigation. Use useRouter() only when you need programmatic navigation from a Client Component.

Common mistakes

• Using router.route and expecting dynamic-param transitions to fire
• Mounting AnimatePresence inside each page instead of _app.tsx
• Forgetting an exit state on the animated page wrapper
• Letting two competing wrappers animate the same page surface

Performance guide

Keep Client Components small

Push Motion to the smallest leaf that actually needs it. A local reveal should not turn an entire page, layout, or data-fetching branch into client code.

Use motion/react-client for passive App Router cases

If the repo already uses the modern motion package and the animation is passive and hook-free, motion/react-client can keep the file server-friendly.

Do not use it for:

• AnimatePresence
• route hooks
• useScroll
• useAnimate
• local interactive state

Plain motion vs m plus LazyMotion

• Use plain motion for local edits and small scopes.
• Use m plus LazyMotion when Motion becomes broad in scope or bundle size is a real concern.

Feature packs

• domAnimation for standard animations, hover, tap, focus, variants, and exit.
• domMax only when you need layout or drag features that require the fuller bundle.

Use MotionConfig for subtree defaults

If multiple components in the same subtree share reduced-motion handling or default transitions, use MotionConfig locally instead of repeating config everywhere.

Lazy-load heavy animation islands

Rarely opened drawers, modals, or dashboards with lots of motion can often be split or loaded lazily. Prefer local dynamic boundaries over global motion infrastructure.

Prefer transform and opacity

These are usually the safest properties to animate. Avoid animating top, left, large filters, or expensive paint-heavy effects on large surfaces.

Layout animation details

• Start with layout before manual height animation.
• If only position should animate, try layout="position".
• If layout animation causes distortion, give affected children their own layout handling.

Scroll performance

• Prefer whileInView for ordinary reveal-on-scroll.
• Reserve useScroll for effects that genuinely need continuous scroll linkage.
• Keep observer and wrapper count under control; one well-placed wrapper often beats many tiny ones.

Protect image layout

When animating next/image or its wrapper:

• preserve the layout box
• keep reserved space intact
• animate transform or opacity rather than intrinsic size

Inspect before optimising blindly

Do not assume Motion is the only source of bundle growth or jank. Check:

• actual import paths
• whether the client boundary widened
• whether a new global provider was added
• whether the route now mounts more animated DOM than before

When not to animate

Skip or reduce Motion when:

• the effect can be handled cleanly in CSS and Motion was not required
• the route is highly performance-sensitive and the effect is purely decorative
• reduced-motion users would receive little value from the movement

Recipes

Examples below use the current motion package. If the repo stays on legacy framer-motion, swap imports consistently.

1) Subtle button micro-interaction

"use client";

import * as React from "react";
import { motion } from "motion/react";

export function MotionButton(
  props: React.ComponentPropsWithoutRef<"button">,
) {
  return (
    <motion.button
      {...props}
      whileHover={{ y: -1 }}
      whileTap={{ scale: 0.98 }}
      transition={{ duration: 0.16, ease: [0.22, 1, 0.36, 1] }}
    />
  );
}

Use for:

• CTA buttons
• icon buttons
• menu triggers

Avoid:

• large scale jumps
• removing visible focus styles

2) Reveal on scroll

"use client";

import * as React from "react";
import { motion } from "motion/react";

export function Reveal({
  children,
  className,
}: {
  children: React.ReactNode;
  className?: string;
}) {
  return (
    <motion.div
      className={className}
      initial={{ opacity: 0, y: 16 }}
      whileInView={{ opacity: 1, y: 0 }}
      viewport={{ once: true, amount: 0.2 }}
      transition={{ duration: 0.28, ease: [0.22, 1, 0.36, 1] }}
    >
      {children}
    </motion.div>
  );
}

Use whileInView for simple reveal. Switch to useInView plus useAnimate only when the timeline is custom.

3) Staggered list

"use client";

import * as React from "react";
import { motion, stagger } from "motion/react";

const container = {
  hidden: {},
  show: {
    transition: {
      delayChildren: stagger(0.06),
    },
  },
};

const item = {
  hidden: { opacity: 0, y: 10 },
  show: { opacity: 1, y: 0 },
};

export function StaggerList({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <motion.ul variants={container} initial="hidden" animate="show">
      {children}
    </motion.ul>
  );
}

export function StaggerItem({
  children,
}: {
  children: React.ReactNode;
}) {
  return <motion.li variants={item}>{children}</motion.li>;
}

Use when many siblings share the same entrance idea.

4) Modal or drawer shell

Pair Motion with a dialog library for semantics and focus management.

"use client";

import * as React from "react";
import { AnimatePresence, motion } from "motion/react";

export function ModalShell({
  open,
  onClose,
  children,
}: {
  open: boolean;
  onClose: () => void;
  children: React.ReactNode;
}) {
  return (
    <AnimatePresence>
      {open ? (
        <>
          <motion.div
            className="fixed inset-0 bg-black/50"
            initial={{ opacity: 0 }}
            animate={{ opacity: 1 }}
            exit={{ opacity: 0 }}
            onClick={onClose}
          />
          <motion.div
            className="fixed inset-x-0 top-20 mx-auto max-w-lg rounded-2xl bg-white p-6 shadow-xl"
            initial={{ opacity: 0, y: 16, scale: 0.98 }}
            animate={{ opacity: 1, y: 0, scale: 1 }}
            exit={{ opacity: 0, y: 8, scale: 0.98 }}
            transition={{ duration: 0.24, ease: [0.22, 1, 0.36, 1] }}
          >
            {children}
          </motion.div>
        </>
      ) : null}
    </AnimatePresence>
  );
}

5) Shared underline for tabs

"use client";

import * as React from "react";
import { LayoutGroup, motion } from "motion/react";

export function Tabs({
  id,
  items,
  value,
  onChange,
}: {
  id: string;
  items: { value: string; label: string }[];
  value: string;
  onChange: (value: string) => void;
}) {
  return (
    <LayoutGroup id={id}>
      <div className="flex gap-4">
        {items.map((item) => {
          const selected = item.value === value;

          return (
            <button
              key={item.value}
              className="relative pb-2"
              onClick={() => onChange(item.value)}
            >
              {item.label}
              {selected ? (
                <motion.div
                  layoutId="underline"
                  className="absolute inset-x-0 -bottom-px h-0.5 rounded-full bg-current"
                />
              ) : null}
            </button>
          );
        })}
      </div>
    </LayoutGroup>
  );
}

Use LayoutGroup id when multiple tab rows may exist on the same page, because layoutId is global.

6) Accordion layout animation

"use client";

import * as React from "react";
import { LayoutGroup, motion } from "motion/react";

export function AccordionItem({
  title,
  children,
}: {
  title: string;
  children: React.ReactNode;
}) {
  const [open, setOpen] = React.useState(false);

  return (
    <motion.section layout className="rounded-xl border">
      <button
        className="w-full p-4 text-left"
        onClick={() => setOpen((value) => !value)}
      >
        {title}
      </button>

      {open ? (
        <motion.div
          layout
          className="px-4 pb-4"
          initial={{ opacity: 0 }}
          animate={{ opacity: 1 }}
          exit={{ opacity: 0 }}
        >
          {children}
        </motion.div>
      ) : null}
    </motion.section>
  );
}

export function Accordion({
  children,
}: {
  children: React.ReactNode;
}) {
  return <LayoutGroup>{children}</LayoutGroup>;
}

7) App Router route shell

Use this when the task explicitly calls for route enter and exit choreography.

"use client";

import * as React from "react";
import { AnimatePresence } from "motion/react";
import { motion } from "motion/react";
import { usePathname } from "next/navigation";

export function RouteTransitionShell({
  children,
}: {
  children: React.ReactNode;
}) {
  const pathname = usePathname();

  return (
    <AnimatePresence initial={false} mode="wait">
      <motion.main
        key={pathname}
        initial={{ opacity: 0, y: 12 }}
        animate={{ opacity: 1, y: 0 }}
        exit={{ opacity: 0, y: -8 }}
        transition={{ duration: 0.28, ease: [0.22, 1, 0.36, 1] }}
      >
        {children}
      </motion.main>
    </AnimatePresence>
  );
}

Mount this shell from a layout so AnimatePresence stays mounted.

8) Pages Router _app.tsx

import type { AppProps } from "next/app";
import { AnimatePresence, MotionConfig } from "motion/react";

export default function App({ Component, pageProps, router }: AppProps) {
  return (
    <MotionConfig reducedMotion="user">
      <AnimatePresence initial={false} mode="wait">
        <Component {...pageProps} key={router.asPath} />
      </AnimatePresence>
    </MotionConfig>
  );
}

9) Scroll progress bar

"use client";

import { motion, useScroll, useSpring } from "motion/react";

export function ScrollProgress() {
  const { scrollYProgress } = useScroll();
  const scaleX = useSpring(scrollYProgress, {
    stiffness: 240,
    damping: 30,
    mass: 0.4,
  });

  return (
    <motion.div
      className="fixed inset-x-0 top-0 h-1 origin-left bg-current"
      style={{ scaleX }}
    />
  );
}

10) Imperative reveal with useAnimate

Use this when the sequence depends on an effect, intersection state, or custom timing that is awkward with props alone.

"use client";

import * as React from "react";
import { useAnimate, useInView, stagger } from "motion/react";

export function ImperativeListReveal({
  children,
}: {
  children: React.ReactNode;
}) {
  const [scope, animate] = useAnimate();
  const inView = useInView(scope, { once: true, amount: 0.2 });

  React.useEffect(() => {
    if (!inView) return;

    void animate(
      "li",
      { opacity: [0, 1], y: [12, 0] },
      { delay: stagger(0.06), duration: 0.24, ease: [0.22, 1, 0.36, 1] },
    );
  }, [animate, inView]);

  return (
    <ul ref={scope}>
      {children}
    </ul>
  );
}

11) Passive App Router card with motion/react-client

import * as motion from "motion/react-client"

export function MotionCard({
  children,
  className,
}: {
  children: React.ReactNode
  className?: string
}) {
  return (
    <motion.article
      className={className}
      initial={{ opacity: 0, y: 8 }}
      animate={{ opacity: 1, y: 0 }}
      transition={{ duration: 0.25, ease: "easeOut" }}
    >
      {children}
    </motion.article>
  )
}

Use this only when you do not need hooks, AnimatePresence, or other client-only logic.

12) Reorder list

"use client"

import { Reorder } from "motion/react"
import { useState } from "react"

export function ReorderList({ initialItems }: { initialItems: string[] }) {
  const [items, setItems] = useState(initialItems)

  return (
    <Reorder.Group axis="y" values={items} onReorder={setItems}>
      {items.map((item) => (
        <Reorder.Item key={item} value={item}>
          {item}
        </Reorder.Item>
      ))}
    </Reorder.Group>
  )
}

Troubleshooting

Nothing animates

• Check that the component actually renders a Motion element such as motion.div.
• Confirm the repo import path is consistent with the installed package.
• Make sure the triggering prop or key is changing when you expect an animation.
• In App Router, verify that client-only Motion imports are not sitting in a server file.

App Router says a component needs use client

You are probably importing motion/react or framer-motion into a server file.

Fixes:

• Move the animated piece into a small Client Component leaf.
• Or, for passive hook-free Motion in a modern Motion codebase, use motion/react-client.
• Do not make app/layout.tsx client-side unless the request truly needs a global client boundary.

Exit animations do not fire

• The exiting element must be a direct child of AnimatePresence.
• The child must have a stable key.
• The presence boundary must stay mounted long enough for the exit to happen.
• In App Router, template remounts alone will not give you a persistent exit-aware shell.

Enter animations run when they should not

• Use initial={false} when the first paint should match the final state.
• Check whether the component is remounting because of a changing key.
• Verify that template.tsx remount semantics are actually wanted.

Dynamic Pages Router routes do not transition

• In _app.tsx, key by router.asPath when dynamic param changes matter.
• Do not key by a value that stays constant across the transitions you care about.

Layout animation is not happening or looks stretched

• Start with layout before manual size choreography.
• If only position should animate, try layout="position".
• If children distort, add layout to affected descendants as well.
• Confirm the layout is actually changing between renders.

Shared-element underline animates in the wrong group

• layoutId is global within the current layout tree.
• In repeated widgets, wrap each instance in LayoutGroup id.
• Ensure only one active shared element with a given layoutId exists per group.

mode="popLayout" looks broken

• The parent needs a non-static position.
• Check for clipping or stacking-context side effects.
• Use it only when you truly need the exiting item popped out of layout.

Scroll reveal fires against the wrong container

• If the scroll container is not the window, configure viewport.root.
• If you need more control, switch to useInView with the correct root.
• Avoid stacking multiple observers when one container-level approach would do.

Motion feels too heavy or distracting

• Reduce distance before reducing duration.
• Prefer opacity plus a small y change.
• Remove bounce from content surfaces unless the design system calls for it.
• Re-check whether Motion is even necessary for the requested effect.

Hydration mismatch or flashing

• Keep the server-rendered structure stable.
• Avoid using route hooks or browser-only APIs in server files.
• Use initial={false} when first paint should not animate in.
• Be careful when wrappers change DOM structure around server-rendered content.

Reduced motion is not handled

• Add MotionConfig reducedMotion="user" at an appropriate subtree boundary.
• Use useReducedMotion() when behaviour, not just timing, should change.
• Replace large movement with opacity-only changes when reasonable.

Styling or refs break after wrapping with Motion

• Prefer converting the existing root element to a Motion element rather than adding an extra wrapper.
• If you must wrap a design-system component, use motion.create() outside render.
• Make sure the wrapped component forwards its ref.

LazyMotion complains or bundle size jumped

• domAnimation is the default feature pack.
• domMax is only for layout, drag, or features that truly need it.
• Keep LazyMotion local to the subtree that benefits from it.
• Check whether a simple local motion import would actually be cheaper operationally for the task.

CSP blocks Motion styles

• Some Motion features rely on runtime style injection.
• Check the project CSP and nonce setup before blaming the component code.
• If CSP is strict, prefer patterns that fit the project’s existing allowances or adjust CSP deliberately.

Template-based transition did not retrigger

• template.tsx remounts on segment changes, not every possible state change.
• Search-param-only changes may not behave the way you expect.
• If you need a guaranteed content transition on pathname change, use a client wrapper keyed by pathname.