motion

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Motion

Overview

概述

Motion (package:

motion

, formerly

framer-motion

) is the standard React animation library. Import from

motion/react

. Provides declarative props for gestures, scroll-linked animations, layout transitions, SVG path drawing, and spring physics. Uses a hybrid animation engine (WAAPI for transforms/opacity, ScrollTimeline for scroll-linked effects). Bundle ranges from 2.3 KB (useAnimate mini) to 34 KB (full), optimizable to 4.6 KB with LazyMotion. Compatible with React 18.2+, React 19, Next.js App Router, and Vite.

Do NOT use Motion for simple list add/remove animations (use AutoAnimate instead at 3.28 KB). Do NOT use for 3D (use Three.js / React Three Fiber).

Motion（包名：

motion

，原

framer-motion

）是React的标准动画库。从

motion/react

导入。提供声明式props用于手势、滚动关联动画、布局过渡、SVG路径绘制和弹簧物理动画。采用混合动画引擎（WAAPI处理变换/透明度，ScrollTimeline处理滚动关联效果）。包体积从2.3 KB（精简版useAnimate）到34 KB（完整版），使用LazyMotion可优化至4.6 KB。兼容React 18.2+、React 19、Next.js App Router和Vite。

请勿将Motion用于简单的列表增删动画（改用AutoAnimate，体积3.28 KB）。请勿用于3D动画（改用Three.js / React Three Fiber）。

Quick Reference

快速参考

Pattern	API / Props
Fade in on mount	`initial` , `animate` , `transition`
Exit animations	`AnimatePresence` + `exit` prop (unique `key` required)
Staggered list	`variants` with `staggerChildren`
Hover / tap / focus	`whileHover` , `whileTap` , `whileFocus`
Drag	`drag` , `dragConstraints` , `dragElastic`
Scroll-triggered	`whileInView` , `viewport={{ once: true }}`
Scroll-linked/parallax	`useScroll` + `useTransform`
Progress indicator	`scrollYProgress` + `scaleX`
Layout animation	`layout` prop (FLIP technique)
Shared element	`layoutId` (same ID across views)
Layout group	`LayoutGroup` wrapping sibling lists
Page transition	`AnimatePresence` + `key={pathname}`
SVG path drawing	`pathLength` on `motion.path`
Animated counter	`useSpring` + `useTransform`
Imperative control	`useAnimate` hook returns `[scope, animate]`
Custom components	`motion.create(Component)` wraps any component
Bundle optimization	`LazyMotion` + `domAnimation` + `m` component (4.6 KB)
Reduced motion	`MotionConfig reducedMotion="user"`

模式	API/Props
挂载时淡入	`initial` , `animate` , `transition`
退出动画	`AnimatePresence` + `exit` prop（需唯一 `key` ）
交错列表	带有 `staggerChildren` 的 `variants`
悬停/点击/聚焦	`whileHover` , `whileTap` , `whileFocus`
拖拽	`drag` , `dragConstraints` , `dragElastic`
滚动触发动画	`whileInView` , `viewport={{ once: true }}`
滚动关联/视差效果	`useScroll` + `useTransform`
进度指示器	`scrollYProgress` + `scaleX`
布局动画	`layout` prop（FLIP技术）
共享元素过渡	`layoutId` （不同视图中使用相同ID）
布局组	`LayoutGroup` 包裹同级列表
页面过渡	`AnimatePresence` + `key={pathname}`
SVG路径绘制动画	`motion.path` 上的 `pathLength`
数字计数器动画	`useSpring` + `useTransform`
命令式控制	`useAnimate` 钩子返回 `[scope, animate]`
自定义组件	`motion.create(Component)` 包裹任意组件
包体积优化	`LazyMotion` + `domAnimation` + `m` 组件（4.6 KB）
减少动画模式	`MotionConfig reducedMotion="user"`

Common Mistakes

常见错误

Mistake	Correct Pattern
AnimatePresence inside a conditional	Keep AnimatePresence mounted; place conditional content inside it
Missing unique `key` on AnimatePresence children	Add unique `key` to each direct child for exit animations
Tailwind `transition-*` classes with Motion animate props	Remove Tailwind transition classes to avoid stuttering
Importing from `framer-motion`	Use `import { motion } from "motion/react"` (renamed late 2024)
Animating 50+ items without virtualization	Use react-window or @tanstack/react-virtual for large lists
Full 34 KB bundle for simple animations	Use LazyMotion + domAnimation (4.6 KB) or useAnimate (2.3 KB)
Missing `"use client"` in Next.js App Router	Add directive or use `motion/react-client` import
Animating `width` / `height` directly	Use `layout` prop or `transform: scale` for GPU acceleration
No `prefers-reduced-motion` handling	Wrap app in `MotionConfig reducedMotion="user"`

错误做法	正确方案
在条件语句内使用AnimatePresence	保持AnimatePresence挂载，将条件内容置于其内部
AnimatePresence子元素缺少唯一 `key`	为每个直接子元素添加唯一 `key` 以支持退出动画
将Tailwind `transition-*` 类与Motion的animate props一起使用	移除Tailwind过渡类以避免动画卡顿
从 `framer-motion` 导入	使用 `import { motion } from "motion/react"` （2024年底重命名）
不对50+个元素的列表做虚拟化处理就进行动画	对大型列表使用react-window或@tanstack/react-virtual
简单动画使用完整版34 KB包	使用LazyMotion + domAnimation（4.6 KB）或useAnimate（2.3 KB）
Next.js App Router中缺少 `"use client"`	添加指令或使用 `motion/react-client` 导入
直接动画 `width` / `height` 属性	使用 `layout` prop或 `transform: scale` 以利用GPU加速
未处理 `prefers-reduced-motion`	用 `MotionConfig reducedMotion="user"` 包裹应用

Delegation

任务委派

Audit animation performance and bundle size: Use
```
Explore
```
agent to find heavy imports, missing LazyMotion, and reflow-triggering properties
Build complex multi-step animations: Use
```
Task
```
agent for scroll-linked parallax, shared layout transitions, and staggered sequences
Plan animation architecture for a new project: Use
```
Plan
```
agent to evaluate Motion vs AutoAnimate vs CSS-only based on requirements

If the
design-system
skill is available, delegate animation token definitions and motion design guidelines to it.

审核动画性能和包体积：使用
```
Explore
```
工具查找冗余导入、未使用LazyMotion的情况以及会触发重排的属性
构建复杂多步骤动画：使用
```
Task
```
工具处理滚动关联视差、共享布局过渡和交错序列
为新项目规划动画架构：使用
```
Plan
```
工具根据需求评估Motion、AutoAnimate和纯CSS方案的适用性

如果
design-system
技能可用，请将动画令牌定义和动效设计准则的任务委派给它。

References

参考资料

Core Patterns -- Animation patterns: fade, exit, stagger, gestures, modal, accordion, tabs, scroll, layout, drag, SVG, loading
Scroll Animations -- useScroll, useTransform, scroll-triggered, parallax, progress indicators, offset configuration
Performance -- LazyMotion, useAnimate, hardware acceleration, virtualization, production checklist
Next.js Integration -- App Router patterns, motion/react-client, Pages Router, known issues
Accessibility & CSS -- prefers-reduced-motion, MotionConfig, useReducedMotion, CSS keyframes, Tailwind animations
Library Selection Guide -- Motion vs AutoAnimate decision guide with feature comparison and use-case recommendations
Troubleshooting -- AnimatePresence bugs, Tailwind conflicts, layout glitches, React 19 issues, naming migration

核心模式 —— 动画模式：淡入、退出、交错、手势、模态框、折叠面板、标签页、滚动、布局、拖拽、SVG、加载
滚动动画 —— useScroll、useTransform、滚动触发动画、视差效果、进度指示器、偏移配置
性能优化 —— LazyMotion、useAnimate、硬件加速、虚拟化、生产环境检查清单
Next.js集成 —— App Router模式、motion/react-client、Pages Router、已知问题
无障碍与CSS —— prefers-reduced-motion、MotionConfig、useReducedMotion、CSS关键帧、Tailwind动画
库选择指南 —— Motion vs AutoAnimate决策指南，包含功能对比和适用场景推荐
问题排查 —— AnimatePresence bug、Tailwind冲突、布局故障、React 19问题、命名迁移