Back to Details

motion

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Motion

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

快速参考

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

常见错误

MistakeCorrect Pattern
AnimatePresence inside a conditionalKeep 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 virtualizationUse react-window or @tanstack/react-virtual for large lists
Full 34 KB bundle for simple animationsUse 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问题、命名迁移