framer-motion-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Community Framer Motion Best Practices

社区版Framer Motion最佳实践

Comprehensive performance optimization guide for Framer Motion animations in React applications. Contains 42 rules across 9 categories, prioritized by impact to guide automated refactoring and code generation.

针对React应用中Framer Motion动画的全面性能优化指南。包含9个分类下的42条规则，按影响优先级排序，可指导自动化重构和代码生成。

When to Apply

适用场景

Reference these guidelines when:

Adding animations to React components with Framer Motion
Optimizing bundle size for animation-heavy applications
Preventing unnecessary re-renders during animations
Implementing layout transitions or shared element animations
Building scroll-linked or gesture-based interactions

在以下场景中参考本指南：

为使用Framer Motion的React组件添加动画
优化动画密集型应用的包体积
防止动画期间不必要的重渲染
实现布局过渡或共享元素动画
构建滚动关联或基于手势的交互

Rule Categories by Priority

按优先级划分的规则分类


bundle-
rerender-
anim-
layout-
scroll-
gesture-
spring-
svg-
exit-

Priority	Category	Impact	Prefix
1	Bundle Optimization	CRITICAL	`bundle-`
2	Re-render Prevention	CRITICAL	`rerender-`
3	Animation Properties	HIGH	`anim-`
4	Layout Animations	HIGH	`layout-`
5	Scroll Animations	MEDIUM-HIGH	`scroll-`
6	Gesture Optimization	MEDIUM	`gesture-`
7	Spring & Physics	MEDIUM	`spring-`
8	SVG & Path Animations	LOW-MEDIUM	`svg-`
9	Exit Animations	LOW	`exit-`


bundle-
rerender-
anim-
layout-
scroll-
gesture-
spring-
svg-
exit-

优先级	分类	影响程度	前缀
1	包体积优化	关键	`bundle-`
2	重渲染预防	关键	`rerender-`
3	动画属性	高	`anim-`
4	布局动画	高	`layout-`
5	滚动动画	中高	`scroll-`
6	手势优化	中	`gesture-`
7	弹簧与物理效果	中	`spring-`
8	SVG与路径动画	中低	`svg-`
9	退出动画	低	`exit-`

Quick Reference

快速参考

1. Bundle Optimization (CRITICAL)

1. 包体积优化（关键）

```
bundle-lazy-motion
```
- Use LazyMotion and m component instead of motion
```
bundle-dynamic-features
```
- Dynamically import motion features
```
bundle-dom-animation
```
- Use domAnimation for basic animations
```
bundle-use-animate-mini
```
- Use mini useAnimate for simple cases
```
bundle-strict-mode
```
- Enable strict mode to catch accidental imports

```
bundle-lazy-motion
```
- 使用LazyMotion和m组件替代motion组件
```
bundle-dynamic-features
```
- 动态导入motion功能
```
bundle-dom-animation
```
- 对基础动画使用domAnimation
```
bundle-use-animate-mini
```
- 对简单场景使用迷你版useAnimate
```
bundle-strict-mode
```
- 启用严格模式以捕获意外导入

2. Re-render Prevention (CRITICAL)

2. 重渲染预防（关键）

```
rerender-motion-value
```
- Use useMotionValue instead of useState
```
rerender-use-transform
```
- Derive values with useTransform
```
rerender-stable-callbacks
```
- Keep animation callbacks stable
```
rerender-variants-object
```
- Define variants outside component
```
rerender-animate-prop
```
- Use stable animate values
```
rerender-motion-value-event
```
- Use motion value events

```
rerender-motion-value
```
- 使用useMotionValue替代useState
```
rerender-use-transform
```
- 通过useTransform派生值
```
rerender-stable-callbacks
```
- 保持动画回调稳定
```
rerender-variants-object
```
- 在组件外部定义variants
```
rerender-animate-prop
```
- 使用稳定的animate值
```
rerender-motion-value-event
```
- 使用motion值事件

3. Animation Properties (HIGH)

3. 动画属性（高）

```
anim-transform-properties
```
- Animate transform properties
```
anim-opacity-filter
```
- Prefer opacity and filter for visual effects
```
anim-hardware-acceleration
```
- Leverage hardware acceleration
```
anim-will-change
```
- Use willChange prop judiciously
```
anim-independent-transforms
```
- Animate transforms independently
```
anim-keyframes-array
```
- Use keyframe arrays for sequences

```
anim-transform-properties
```
- 为transform属性添加动画
```
anim-opacity-filter
```
- 优先使用opacity和filter实现视觉效果
```
anim-hardware-acceleration
```
- 利用硬件加速
```
anim-will-change
```
- 谨慎使用willChange属性
```
anim-independent-transforms
```
- 独立为transform属性添加动画
```
anim-keyframes-array
```
- 使用关键帧数组实现序列动画

4. Layout Animations (HIGH)

4. 布局动画（高）

```
layout-dependency
```
- Use layoutDependency to limit measurements
```
layout-position-size
```
- Use layout="position" or "size" appropriately
```
layout-group
```
- Group related layout animations
```
layout-id-shared
```
- Use layoutId for shared element transitions
```
layout-scroll
```
- Add layoutScroll to scrollable ancestors

```
layout-dependency
```
- 使用layoutDependency限制测量范围
```
layout-position-size
```
- 合理使用layout="position"或"size"
```
layout-group
```
- 对相关布局动画进行分组
```
layout-id-shared
```
- 使用layoutId实现共享元素过渡
```
layout-scroll
```
- 为可滚动祖先元素添加layoutScroll

5. Scroll Animations (MEDIUM-HIGH)

5. 滚动动画（中高）

```
scroll-use-scroll
```
- Use useScroll hook for scroll-linked animations
```
scroll-use-spring-smooth
```
- Smooth scroll animations with useSpring
```
scroll-element-tracking
```
- Track specific elements entering viewport
```
scroll-offset-configuration
```
- Configure scroll offsets
```
scroll-container-ref
```
- Track scroll within specific containers

```
scroll-use-scroll
```
- 使用useScroll钩子实现滚动关联动画
```
scroll-use-spring-smooth
```
- 结合useSpring实现平滑滚动动画
```
scroll-element-tracking
```
- 追踪特定元素进入视口的状态
```
scroll-offset-configuration
```
- 配置滚动偏移量
```
scroll-container-ref
```
- 追踪特定容器内的滚动状态

6. Gesture Optimization (MEDIUM)

6. 手势优化（中）

```
gesture-while-props
```
- Use whileHover/whileTap instead of handlers
```
gesture-variants-flow
```
- Let gesture variants flow to children
```
gesture-drag-constraints
```
- Use dragConstraints ref for boundaries
```
gesture-drag-elastic
```
- Configure dragElastic for natural feel
```
gesture-tap-cancel
```
- Use onTapCancel for interrupted gestures

```
gesture-while-props
```
- 使用whileHover/whileTap替代事件处理器
```
gesture-variants-flow
```
- 让手势变体效果传递给子组件
```
gesture-drag-constraints
```
- 使用dragConstraints ref定义拖拽边界
```
gesture-drag-elastic
```
- 配置dragElastic实现自然拖拽手感
```
gesture-tap-cancel
```
- 使用onTapCancel处理中断的手势

7. Spring & Physics (MEDIUM)

7. 弹簧与物理效果（中）

```
spring-physics-based
```
- Use physics-based springs for interruptibility
```
spring-damping-ratio
```
- Configure damping to control oscillation
```
spring-mass-inertia
```
- Adjust mass for heavier/lighter feel
```
spring-use-spring-hook
```
- Use useSpring for reactive values

```
spring-physics-based
```
- 使用基于物理的弹簧效果以支持中断操作
```
spring-damping-ratio
```
- 配置阻尼参数控制振荡效果
```
spring-mass-inertia
```
- 调整质量参数实现轻重不同的动画手感
```
spring-use-spring-hook
```
- 使用useSpring钩子处理响应式值

8. SVG & Path Animations (LOW-MEDIUM)

8. SVG与路径动画（中低）

```
svg-path-length
```
- Use pathLength for line drawing animations
```
svg-motion-components
```
- Use motion.path and motion.circle
```
svg-viewbox-animation
```
- Animate viewBox for zoom effects
```
svg-morph-matching-points
```
- Match point counts for morphing

```
svg-path-length
```
- 使用pathLength实现路径绘制动画
```
svg-motion-components
```
- 使用motion.path和motion.circle组件
```
svg-viewbox-animation
```
- 为viewBox添加动画实现缩放效果
```
svg-morph-matching-points
```
- 匹配路径点数以实现平滑变形

9. Exit Animations (LOW)

9. 退出动画（低）

```
exit-animate-presence
```
- Wrap conditional renders with AnimatePresence
```
exit-unique-keys
```
- Provide unique keys for AnimatePresence children
```
exit-mode-wait
```
- Use mode="wait" for sequential transitions

```
exit-animate-presence
```
- 用AnimatePresence包裹条件渲染的元素
```
exit-unique-keys
```
- 为AnimatePresence的子元素提供唯一key
```
exit-mode-wait
```
- 使用mode="wait"实现序列过渡效果

How to Use

使用方法

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Rule template - Template for adding new rules

阅读单个参考文件以获取详细说明和代码示例：

章节定义 - 分类结构和影响级别说明
规则模板 - 添加新规则的模板

Reference Files

参考文件

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information

文件	说明
references/_sections.md	分类定义和排序规则
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息