AutoAnimate

Status: Production Ready ✅ Last Updated: 2025-11-07 Dependencies: None (works with any React setup) Latest Versions: @formkit/auto-animate@0.9.0

状态：已就绪可用于生产环境 ✅ 最后更新：2025-11-07 依赖项：无（兼容任意React环境） 最新版本：@formkit/auto-animate@0.9.0

Quick Start (2 Minutes)

快速开始（2分钟）

1. Install AutoAnimate

1. 安装AutoAnimate

bash

pnpm add @formkit/auto-animate

Why this matters:

Only 3.28 KB gzipped (vs 22 KB for Motion)
Zero dependencies
Framework-agnostic (React, Vue, Svelte, vanilla JS)

bash

pnpm add @formkit/auto-animate

重要性说明：

压缩后仅3.28 KB（对比Motion的22 KB）
无任何依赖
框架无关（支持React、Vue、Svelte、原生JS）

2. Add to Your Component

2. 在组件中引入

tsx

import { useAutoAnimate } from "@formkit/auto-animate/react";

export function MyList() {
  const [parent] = useAutoAnimate(); // 1. Get ref

  return (
    <ul ref={parent}> {/* 2. Attach to parent */}
      {items.map(item => (
        <li key={item.id}>{item.text}</li> {/* 3. That's it! */}
      ))}
    </ul>
  );
}

CRITICAL:

✅ Always use unique, stable keys for list items
✅ Parent element must always be rendered (not conditional)
✅ AutoAnimate respects
```
prefers-reduced-motion
```
automatically
✅ Works on add, remove, AND reorder operations

tsx

import { useAutoAnimate } from "@formkit/auto-animate/react";

export function MyList() {
  const [parent] = useAutoAnimate(); // 1. 获取ref

  return (
    <ul ref={parent}> {/* 2. 绑定到父元素 */}
      {items.map(item => (
        <li key={item.id}>{item.text}</li> {/* 3. 完成！ */}
      ))}
    </ul>
  );
}

关键注意事项：

✅ 始终为列表项使用唯一、稳定的key
✅ 父元素必须始终保持渲染（不能是条件渲染）
✅ AutoAnimate会自动遵循
```
prefers-reduced-motion
```
设置
✅ 支持元素的添加、移除和重新排序操作的动画

3. Use in Production (SSR-Safe)

3. 生产环境使用（SSR兼容）

For Cloudflare Workers or Next.js:

tsx

// Use client-only import to prevent SSR errors
import { useState, useEffect } from "react";

export function useAutoAnimateSafe<T extends HTMLElement>() {
  const [parent, setParent] = useState<T | null>(null);

  useEffect(() => {
    if (typeof window !== "undefined" && parent) {
      import("@formkit/auto-animate").then(({ default: autoAnimate }) => {
        autoAnimate(parent);
      });
    }
  }, [parent]);

  return [parent, setParent] as const;
}

针对Cloudflare Workers或Next.js：

tsx

// 使用仅客户端导入避免SSR错误
import { useState, useEffect } from "react";

export function useAutoAnimateSafe<T extends HTMLElement>() {
  const [parent, setParent] = useState<T | null>(null);

  useEffect(() => {
    if (typeof window !== "undefined" && parent) {
      import("@formkit/auto-animate").then(({ default: autoAnimate }) => {
        autoAnimate(parent);
      });
    }
  }, [parent]);

  return [parent, setParent] as const;
}

Known Issues Prevention

已知问题预防

This skill prevents 10+ documented issues:

本方案可避免**10+**个已记录的问题：

Issue #1: SSR/Next.js Import Errors

问题1：SSR/Next.js导入错误

Error: "Can't import the named export 'useEffect' from non EcmaScript module" Source: https://github.com/formkit/auto-animate/issues/55 Why It Happens: AutoAnimate uses DOM APIs not available on server Prevention: Use dynamic imports (see

templates/vite-ssr-safe.tsx

)

错误信息："无法从非ECMAScript模块导入命名导出'useEffect'" 来源：https://github.com/formkit/auto-animate/issues/55 原因：AutoAnimate使用了服务端不可用的DOM API 解决方法：使用动态导入（参考

templates/vite-ssr-safe.tsx

）

Issue #2: Conditional Parent Rendering

问题2：父元素条件渲染

Error: Animations don't work when parent is conditional Source: https://github.com/formkit/auto-animate/issues/8 Why It Happens: Ref can't attach to non-existent element Prevention:

tsx

// ❌ Wrong
{showList && <ul ref={parent}>...</ul>}

// ✅ Correct
<ul ref={parent}>{showList && items.map(...)}</ul>

错误现象：父元素条件渲染时动画失效来源：https://github.com/formkit/auto-animate/issues/8 原因：ref无法绑定到不存在的元素 解决方法：

tsx

// ❌ 错误写法
{showList && <ul ref={parent}>...</ul>}

// ✅ 正确写法
<ul ref={parent}>{showList && items.map(...)}</ul>

Issue #3: Missing Unique Keys

问题3：缺少唯一Key

Error: Items don't animate correctly or flash Source: Official docs Why It Happens: React can't track which items changed Prevention: Always use unique, stable keys (

key={item.id}

)

错误现象：元素动画异常或出现闪烁来源：官方文档原因：React无法追踪元素变化 解决方法：始终使用唯一、稳定的key（

key={item.id}

）

Issue #4: Flexbox Width Issues

问题4：Flexbox宽度问题

Error: Elements snap to width instead of animating smoothly Source: Official docs Why It Happens:

flex-grow: 1

waits for surrounding content Prevention: Use explicit width instead of flex-grow for animated elements

错误现象：元素直接跳转到目标宽度而非平滑动画来源：官方文档原因：

flex-grow: 1

会等待周边内容加载完成 解决方法：为动画元素设置明确宽度，而非使用flex-grow

Issue #5: Table Row Display Issues

问题5：表格行显示异常

Error: Table structure breaks when removing rows Source: https://github.com/formkit/auto-animate/issues/7 Why It Happens: Display: table-row conflicts with animations Prevention: Apply to

<tbody>

instead of individual rows, or use div-based layouts

错误现象：删除行时表格结构破坏来源：https://github.com/formkit/auto-animate/issues/7 原因：display: table-row与动画冲突 解决方法：将ref绑定到

<tbody>

而非单个行，或使用基于div的布局

Issue #6: Jest Testing Errors

问题6：Jest测试错误

Error: "Cannot find module '@formkit/auto-animate/react'" Source: https://github.com/formkit/auto-animate/issues/29 Why It Happens: Jest doesn't resolve ESM exports correctly Prevention: Configure

moduleNameMapper

in jest.config.js

错误信息："找不到模块'@formkit/auto-animate/react'" 来源：https://github.com/formkit/auto-animate/issues/29 原因：Jest无法正确解析ESM导出 解决方法：在jest.config.js中配置

moduleNameMapper

Issue #7: esbuild Compatibility

问题7：esbuild兼容性问题

Error: "Path '.' not exported by package" Source: https://github.com/formkit/auto-animate/issues/36 Why It Happens: ESM/CommonJS condition mismatch Prevention: Configure esbuild to handle ESM modules properly

错误信息："路径'.'未被包导出" 来源：https://github.com/formkit/auto-animate/issues/36 原因：ESM/CommonJS模块格式不匹配 解决方法：配置esbuild以正确处理ESM模块

Issue #8: CSS Position Side Effects

问题8：CSS定位副作用

Error: Layout breaks after adding AutoAnimate Source: Official docs Why It Happens: Parent automatically gets

position: relative

Prevention: Account for position change in CSS or set explicitly

错误现象：添加AutoAnimate后布局破坏来源：官方文档原因：父元素会自动被设置为

position: relative

解决方法：在CSS中考虑该变化或显式设置定位

Issue #9: Vue/Nuxt Registration Errors

问题9：Vue/Nuxt注册错误

Error: "Failed to resolve directive: auto-animate" Source: https://github.com/formkit/auto-animate/issues/43 Why It Happens: Plugin not registered correctly Prevention: Proper plugin setup in Vue/Nuxt config (see references/)

错误信息："无法解析指令:auto-animate" 来源：https://github.com/formkit/auto-animate/issues/43 原因：插件未正确注册 解决方法：在Vue/Nuxt配置中正确注册插件（参考references/）

Issue #10: Angular ESM Issues

问题10：Angular ESM问题

Error: Build fails with "ESM-only package" Source: https://github.com/formkit/auto-animate/issues/72 Why It Happens: CommonJS build environment Prevention: Configure ng-packagr for Angular Package Format

错误现象：构建失败提示"仅支持ESM的包" 来源：https://github.com/formkit/auto-animate/issues/72 原因：使用CommonJS构建环境 解决方法：配置ng-packagr以兼容Angular包格式

When to Use AutoAnimate vs Motion

AutoAnimate与Motion的使用场景对比

Use AutoAnimate When:

优先选择AutoAnimate的场景：

✅ Simple list transitions (add/remove/sort)
✅ Accordion expand/collapse
✅ Toast notifications fade in/out
✅ Form validation messages appear/disappear
✅ Zero configuration preferred
✅ Small bundle size critical (3.28 KB)
✅ Applying to existing/3rd-party code
✅ "Good enough" animations acceptable

✅ 简单列表过渡（添加/移除/排序）
✅ 手风琴展开/收起
✅ 提示通知淡入淡出
✅ 表单验证消息显示/隐藏
✅ 偏好零配置
✅ 包体积要求严格（3.28 KB）
✅ 应用于现有/第三方代码
✅ 接受"足够好"的动画效果

Use Motion When:

优先选择Motion的场景：

✅ Complex choreographed animations
✅ Gesture controls (drag, swipe, hover)
✅ Scroll-based animations
✅ Spring physics animations
✅ SVG path animations
✅ Keyframe control needed
✅ Animation variants/orchestration
✅ Custom easing curves

Rule of Thumb: Use AutoAnimate for 90% of cases, Motion for hero/interactive animations.

✅ 复杂编排动画
✅ 手势控制（拖拽、滑动、悬停）
✅ 滚动触发动画
✅ 弹簧物理动画
✅ SVG路径动画
✅ 需要关键帧控制
✅ 动画变体/编排
✅ 自定义缓动曲线

经验法则：90%的场景使用AutoAnimate，英雄/交互类复杂动画使用Motion。

Critical Rules

核心规则

Always Do

必须遵守

✅ Use unique, stable keys -

key={item.id}

not

key={index}

✅ Keep parent in DOM - Parent ref element always rendered ✅ Client-only for SSR - Dynamic import for server environments ✅ Respect accessibility - Keep

disrespectUserMotionPreference: false

✅ Test with motion disabled - Verify UI works without animations ✅ Use explicit width - Avoid flex-grow on animated elements ✅ Apply to tbody for tables - Not individual rows

✅ 使用唯一稳定的key - 使用

key={item.id}

而非

key={index}

✅ 保持父元素在DOM中 - 绑定ref的父元素需始终渲染 ✅ SSR场景仅客户端导入 - 服务端环境使用动态导入 ✅ 遵循无障碍标准 - 保持

disrespectUserMotionPreference: false

✅ 测试无动画场景 - 验证关闭动画后UI仍正常工作 ✅ 使用明确宽度 - 避免为动画元素使用flex-grow ✅ 表格场景绑定到tbody - 而非单个行元素

Never Do

禁止操作

❌ Conditional parent -

{show && <ul ref={parent}>}

❌ Index as key -

key={index}

breaks animations ❌ Ignore SSR - Will break in Cloudflare Workers/Next.js ❌ Force animations -

disrespectUserMotionPreference: true

breaks accessibility ❌ Animate tables directly - Use tbody or div-based layout ❌ Skip unique keys - Required for proper animation ❌ Complex animations - Use Motion instead

❌ 父元素条件渲染 - 如

{show && <ul ref={parent}>}

❌ 使用索引作为key -

key={index}

会破坏动画 ❌ 忽略SSR场景 - 在Cloudflare Workers/Next.js中会报错 ❌ 强制动画 -

disrespectUserMotionPreference: true

违反无障碍标准 ❌ 直接动画表格行 - 使用tbody或基于div的布局 ❌ 跳过唯一key - 这是动画正常工作的必要条件 ❌ 实现复杂动画 - 此类场景请使用Motion

Configuration

配置选项

AutoAnimate is zero-config by default. Optional customization:

tsx

import { useAutoAnimate } from "@formkit/auto-animate/react";

const [parent] = useAutoAnimate({
  duration: 250, // milliseconds (default: 250)
  easing: "ease-in-out", // CSS easing (default: "ease-in-out")
  // disrespectUserMotionPreference: false, // Keep false!
});

Recommendation: Use defaults unless you have specific design requirements.

AutoAnimate默认零配置，支持以下可选自定义：

tsx

import { useAutoAnimate } from "@formkit/auto-animate/react";

const [parent] = useAutoAnimate({
  duration: 250, // 动画时长（毫秒，默认250）
  easing: "ease-in-out", // CSS缓动函数（默认"ease-in-out"）
  // disrespectUserMotionPreference: false, // 保持默认值！
});

建议：除非有特定设计需求，否则使用默认配置。

Using Bundled Resources

配套资源使用

Templates (templates/)

模板文件（templates/）

Copy-paste ready examples:

```
react-basic.tsx
```
- Simple list with add/remove/shuffle
```
react-typescript.tsx
```
- Typed setup with custom config
```
filter-sort-list.tsx
```
- Animated filtering and sorting
```
accordion.tsx
```
- Expandable sections
```
toast-notifications.tsx
```
- Fade in/out messages
```
form-validation.tsx
```
- Error messages animation
```
vite-ssr-safe.tsx
```
- Cloudflare Workers/SSR pattern

可直接复制使用的示例：

```
react-basic.tsx
```
- 包含添加/移除/打乱操作的简单列表
```
react-typescript.tsx
```
- 带自定义配置的TypeScript示例
```
filter-sort-list.tsx
```
- 带动画的筛选和排序列表
```
accordion.tsx
```
- 可展开收起的手风琴组件
```
toast-notifications.tsx
```
- 淡入淡出的提示通知
```
form-validation.tsx
```
- 带动画的表单错误提示
```
vite-ssr-safe.tsx
```
- Cloudflare Workers/SSR兼容方案

References (references/)

参考文档（references/）

```
auto-animate-vs-motion.md
```
- Decision guide for which to use
```
css-conflicts.md
```
- Flexbox, table, and position gotchas
```
ssr-patterns.md
```
- Next.js, Nuxt, Workers workarounds

```
auto-animate-vs-motion.md
```
- 库选择决策指南
```
css-conflicts.md
```
- Flexbox、表格和定位相关问题解决
```
ssr-patterns.md
```
- Next.js、Nuxt、Workers的兼容方案

Scripts (scripts/)

脚本文件（scripts/）

```
init-auto-animate.sh
```
- Automated setup script

```
init-auto-animate.sh
```
- 自动化安装脚本

Cloudflare Workers Compatibility

Cloudflare Workers兼容性

AutoAnimate works perfectly with Cloudflare Workers Static Assets:

✅ Client-side only - Runs in browser, not Worker runtime ✅ No Node.js deps - Pure browser code ✅ Edge-friendly - 3.28 KB gzipped ✅ SSR-safe - Use dynamic imports (see templates/)

Vite Config:

typescript

export default defineConfig({
  plugins: [react(), cloudflare()],
  ssr: {
    external: ["@formkit/auto-animate"],
  },
});

AutoAnimate完美兼容Cloudflare Workers静态资源：

✅ 仅客户端运行 - 在浏览器中执行，不占用Worker运行时资源 ✅ 无Node.js依赖 - 纯浏览器端代码 ✅ 边缘友好 - 仅3.28 KB压缩体积 ✅ SSR兼容 - 使用动态导入（参考模板文件）

Vite配置示例：

typescript

export default defineConfig({
  plugins: [react(), cloudflare()],
  ssr: {
    external: ["@formkit/auto-animate"],
  },
});

Accessibility

无障碍支持

AutoAnimate respects

prefers-reduced-motion

automatically:

css

/* User's system preference */
@media (prefers-reduced-motion: reduce) {
  /* AutoAnimate disables animations automatically */
}

Critical: Never set

disrespectUserMotionPreference: true

- this breaks accessibility.

AutoAnimate会自动遵循

prefers-reduced-motion

设置：

css

/* 用户系统偏好设置 */
@media (prefers-reduced-motion: reduce) {
  /* AutoAnimate会自动禁用动画 */
}

关键提醒：永远不要设置

disrespectUserMotionPreference: true

——这会违反无障碍标准。

Official Documentation

官方文档

Official Site: https://auto-animate.formkit.com
GitHub: https://github.com/formkit/auto-animate
npm: https://www.npmjs.com/package/@formkit/auto-animate
React Docs: https://auto-animate.formkit.com/react
Video Tutorial: Laracasts video (see README)

官方网站：https://auto-animate.formkit.com
GitHub仓库：https://github.com/formkit/auto-animate
npm包：https://www.npmjs.com/package/@formkit/auto-animate
React文档：https://auto-animate.formkit.com/react
视频教程：Laracasts视频（参考README）

Package Versions (Verified 2025-11-07)

验证通过的包版本（2025-11-07）

json

{
  "dependencies": {
    "@formkit/auto-animate": "^0.9.0"
  },
  "devDependencies": {
    "react": "^19.2.0",
    "vite": "^6.0.0"
  }
}

json

{
  "dependencies": {
    "@formkit/auto-animate": "^0.9.0"
  },
  "devDependencies": {
    "react": "^19.2.0",
    "vite": "^6.0.0"
  }
}

Production Example

生产环境验证示例

This skill is based on production testing:

Bundle Size: 3.28 KB gzipped
Setup Time: 2 minutes (vs 15 min with Motion)
Errors: 0 (all 10 known issues prevented)
Validation: ✅ Works with Vite, Tailwind v4, Cloudflare Workers, React 19

Tested Scenarios:

✅ Filter/sort lists
✅ Accordion components
✅ Toast notifications
✅ Form validation messages
✅ SSR/Cloudflare Workers
✅ Accessibility (prefers-reduced-motion)

本方案基于生产环境测试：

包体积：3.28 KB压缩后
配置时间：2分钟（对比Motion的15分钟）
错误数：0（已预防所有10个已知问题）
兼容性：✅ 支持Vite、Tailwind v4、Cloudflare Workers、React 19

测试场景覆盖：

✅ 筛选/排序列表
✅ 手风琴组件
✅ 提示通知
✅ 表单验证消息
✅ SSR/Cloudflare Workers
✅ 无障碍支持（prefers-reduced-motion）

Troubleshooting

故障排查

Problem: Animations not working

问题：动画不生效

Solution: Check these common issues:

Is parent element always in DOM? (not conditional)
Do items have unique, stable keys?
Is ref attached to immediate parent of animated children?

解决方案：检查以下常见问题：

父元素是否始终在DOM中？（非条件渲染）
列表项是否有唯一稳定的key？
ref是否绑定到动画子元素的直接父元素？

Problem: SSR/Next.js errors

问题：SSR/Next.js报错

Solution: Use dynamic import:

tsx

useEffect(() => {
  if (typeof window !== "undefined") {
    import("@formkit/auto-animate").then(({ default: autoAnimate }) => {
      autoAnimate(parent);
    });
  }
}, [parent]);

解决方案：使用动态导入：

tsx

useEffect(() => {
  if (typeof window !== "undefined") {
    import("@formkit/auto-animate").then(({ default: autoAnimate }) => {
      autoAnimate(parent);
    });
  }
}, [parent]);

Problem: Items flash instead of animating

问题：元素闪烁而非平滑动画

Solution: Add unique keys:

key={item.id}

not

key={index}

解决方案：添加唯一key：使用

key={item.id}

而非

key={index}

Problem: Flexbox width issues

问题：Flexbox宽度异常

Solution: Use explicit width instead of

flex-grow: 1

解决方案：使用明确宽度代替`flex-grow: <[SILENT_never_used_51bce0c785ca2f68081bfa7d91973934]>{ "description": "经过生产环境验证的AutoAnimate（@formkit/auto-animate）配置方案——这是一款零配置、即插即用的动画库，当DOM元素被添加、移除或移动时，会自动添加平滑过渡效果。当你构建的UI需要为列表、手风琴组件、提示通知或表单验证消息添加简单的自动动画，且不想使用复杂的全量动画库时，就可以使用该方案。

适用场景：为动态列表添加平滑动画、构建筛选/排序界面、创建手风琴组件、实现提示通知、为表单验证消息添加动画效果、无需编写动画代码即可实现简单过渡、使用Vite + React + Tailwind技术栈、部署到Cloudflare Workers静态资源，或者遇到动画库的SSR错误时。

关键词：auto-animate, @formkit/auto-animate, formkit, 零配置动画, 自动动画, 即插即用动画, 列表动画, 手风琴动画, 提示通知动画, 表单验证动画, 轻量动画, 2KB动画, prefers-reduced-motion, 无障碍动画, vite react动画, cloudflare workers动画, ssr安全动画", "content": "# AutoAnimate

状态：已就绪可用于生产环境 ✅ 最后更新：2025-11-07 依赖项：无（兼容任意React环境） 最新版本：@formkit/auto-animate@0.9.0

Problem: Table rows don't animate

快速开始（2分钟）

—

1. 安装AutoAnimate

Solution: Apply ref to

<tbody>

, not individual

<tr>

elements

bash

pnpm add @formkit/auto-animate

重要性说明：

压缩后仅3.28 KB（对比Motion的22 KB）
无任何依赖
框架无关（支持React、Vue、Svelte、原生JS）

Complete Setup Checklist

2. 在组件中引入

Installed
```
@formkit/auto-animate@0.9.0
```
Using React 19+ (or Vue/Svelte)
Added ref to parent element
Parent element always rendered (not conditional)
List items have unique, stable keys
Tested with
```
prefers-reduced-motion
```
SSR-safe if using Cloudflare Workers/Next.js
No flexbox width issues
Dev server runs without errors
Production build succeeds

Questions? Issues?

Check
```
templates/
```
for working examples
Check
```
references/auto-animate-vs-motion.md
```
for library comparison
Check
```
references/ssr-patterns.md
```
for SSR workarounds
Check official docs: https://auto-animate.formkit.com
Check GitHub issues: https://github.com/formkit/auto-animate/issues

Production Ready? ✅ Yes - 13.6k stars, actively maintained, zero dependencies.

tsx

import { useAutoAnimate } from "@formkit/auto-animate/react";

export function MyList() {
  const [parent] = useAutoAnimate(); // 1. 获取ref

  return (
    <ul ref={parent}> {/* 2. 绑定到父元素 */}
      {items.map(item => (
        <li key={item.id}>{item.text}</li> {/* 3. 完成！ */}
      ))}
    </ul>
  );
}

关键注意事项：

✅ 始终为列表项使用唯一、稳定的key
✅ 父元素必须始终保持渲染（不能是条件渲染）
✅ AutoAnimate会自动遵循
```
prefers-reduced-motion
```
设置
✅ 支持元素的添加、移除和重新排序操作的动画

—

3. 生产环境使用（SSR兼容）

—

针对Cloudflare Workers或Next.js：

tsx

// 使用仅客户端导入避免SSR错误
import { useState, useEffect } from "react";

export function useAutoAnimateSafe<T extends HTMLElement>() {
  const [parent, setParent] = useState<T | null>(null);

  useEffect(() => {
    if (typeof window !== "undefined" && parent) {
      import("@formkit/auto-animate").then(({ default: autoAnimate }) => {
        autoAnimate(parent);
      });
    }
  }, [parent]);

  return [parent, setParent] as const;
}

—

已知问题预防

—

本方案可避免**10+**个已记录的问题：

—

问题1：SSR/Next.js导入错误

—

错误信息："无法从非ECMAScript模块导入命名导出'useEffect'" 来源：https://github.com/formkit/auto-animate/issues/55 原因：AutoAnimate使用了服务端不可用的DOM API 解决方法：使用动态导入（参考

templates/vite-ssr-safe.tsx

）

—

问题2：父元素条件渲染

—

错误现象：父元素条件渲染时动画失效来源：https://github.com/formkit/auto-animate/issues/8 原因：ref无法绑定到不存在的元素 解决方法：

tsx

// ❌ 错误写法
{showList && <ul ref={parent}>...</ul>}

// ✅ 正确写法
<ul ref={parent}>{showList && items.map(...)}</ul>

—

问题3：缺少唯一Key

—

错误现象：元素动画异常或出现闪烁来源：官方文档原因：React无法追踪元素变化 解决方法：始终使用唯一、稳定的key（

key={item.id}

）

—

问题4：Flexbox宽度问题

—

错误现象：元素直接跳转到目标宽度而非平滑动画来源：官方文档原因：

flex-grow: 1

会等待周边内容加载完成 解决方法：为动画元素设置明确宽度，而非使用flex-grow

—

问题5：表格行显示异常

—

错误现象：删除行时表格结构破坏来源：https://github.com/formkit/auto-animate/issues/7 原因：display: table-row与动画冲突 解决方法：将ref绑定到

<tbody>

而非单个行，或使用基于div的布局

—

问题6：Jest测试错误

—

错误信息："找不到模块'@formkit/auto-animate/react'" 来源：https://github.com/formkit/auto-animate/issues/29 原因：Jest无法正确解析ESM导出 解决方法：在jest.config.js中配置

moduleNameMapper

—

问题7：esbuild兼容性问题

—

错误信息："路径'.'未被包导出" 来源：https://github.com/formkit/auto-animate/issues/36 原因：ESM/CommonJS模块格式不匹配 解决方法：配置esbuild以正确处理ESM模块

—

问题8：CSS定位副作用

—

错误现象：添加AutoAnimate后布局破坏来源：官方文档原因：父元素会自动被设置为

position: relative

解决方法：在CSS中考虑该变化或显式设置定位

—

问题9：Vue/Nuxt注册错误

—

错误信息："无法解析指令:auto-animate" 来源：https://github.com/formkit/auto-animate/issues/43 原因：插件未正确注册 解决方法：在Vue/Nuxt配置中正确注册插件（参考references/）

—

问题10：Angular ESM问题

—

错误现象：构建失败提示"仅支持ESM的包" 来源：https://github.com/formkit/auto-animate/issues/72 原因：使用CommonJS构建环境 解决方法：配置ng-packagr以兼容Angular包格式

—

AutoAnimate与Motion的使用场景对比

—

优先选择AutoAnimate的场景：

—

✅ 简单列表过渡（添加/移除/排序）
✅ 手风琴展开/收起
✅ 提示通知淡入淡出
✅ 表单验证消息显示/隐藏
✅ 偏好零配置
✅ 包体积要求严格（3.28 KB）
✅ 应用于现有/第三方代码
✅ 接受"足够好"的动画效果

—

优先选择Motion的场景：

—

✅ 复杂编排动画
✅ 手势控制（拖拽、滑动、悬停）
✅ 滚动触发动画
✅ 弹簧物理动画
✅ SVG路径动画
✅ 需要关键帧控制
✅ 动画变体/编排
✅ 自定义缓动曲线

经验法则：90%的场景使用AutoAnimate，英雄/交互类复杂动画使用Motion。

—

核心规则

—

必须遵守

—

✅ 使用唯一稳定的key - 使用

key={item.id}

而非

key={index}

✅ 保持父元素在DOM中 - 绑定ref的父元素需始终渲染 ✅ SSR场景仅客户端导入 - 服务端环境使用动态导入 ✅ 遵循无障碍标准 - 保持

disrespectUserMotionPreference: false

✅ 测试无动画场景 - 验证关闭动画后UI仍正常工作 ✅ 使用明确宽度 - 避免为动画元素使用flex-grow ✅ 表格场景绑定到tbody - 而非单个行元素

—

禁止操作

—

❌ 父元素条件渲染 - 如

{show && <ul ref={parent}>}

❌ 使用索引作为key -

key={index}

会破坏动画 ❌ 忽略SSR场景 - 在Cloudflare Workers/Next.js中会报错 ❌ 强制动画 -

disrespectUserMotionPreference: true

违反无障碍标准 ❌ 直接动画表格行 - 使用tbody或基于div的布局 ❌ 跳过唯一key - 这是动画正常工作的必要条件 ❌ 实现复杂动画 - 此类场景请使用Motion

—

配置选项

—

AutoAnimate默认零配置，支持以下可选自定义：

tsx

import { useAutoAnimate } from "@formkit/auto-animate/react";

const [parent] = useAutoAnimate({
  duration: 250, // 动画时长（毫秒，默认250）
  easing: "ease-in-out", // CSS缓动函数（默认"ease-in-out"）
  // disrespectUserMotionPreference: false, // 保持默认值！
});

建议：除非有特定设计需求，否则使用默认配置。

—

配套资源使用

—

模板文件（templates/）

—

可直接复制使用的示例：

```
react-basic.tsx
```
- 包含添加/移除/打乱操作的简单列表
```
react-typescript.tsx
```
- 带自定义配置的TypeScript示例
```
filter-sort-list.tsx
```
- 带动画的筛选和排序列表
```
accordion.tsx
```
- 可展开收起的手风琴组件
```
toast-notifications.tsx
```
- 淡入淡出的提示通知
```
form-validation.tsx
```
- 带动画的表单错误提示
```
vite-ssr-safe.tsx
```
- Cloudflare Workers/SSR兼容方案

—

参考文档（references/）

—

```
auto-animate-vs-motion.md
```
- 库选择决策指南
```
css-conflicts.md
```
- Flexbox、表格和定位相关问题解决
```
ssr-patterns.md
```
- Next.js、Nuxt、Workers的兼容方案

—

脚本文件（scripts/）

—

```
init-auto-animate.sh
```
- 自动化安装脚本

—

Cloudflare Workers兼容性

—

AutoAnimate完美兼容Cloudflare Workers静态资源：

✅ 仅客户端运行 - 在浏览器中执行，不占用Worker运行时资源 ✅ 无Node.js依赖 - 纯浏览器端代码 ✅ 边缘友好 - 仅3.28 KB压缩体积 ✅ SSR兼容 - 使用动态导入（参考模板文件）

Vite配置示例：

typescript

export default defineConfig({
  plugins: [react(), cloudflare()],
  ssr: {
    external: ["@formkit/auto-animate"],
  },
});

—

无障碍支持

—

AutoAnimate会自动遵循

prefers-reduced-motion

设置：

css

/* 用户系统偏好设置 */
@media (prefers-reduced-motion: reduce) {
  /* AutoAnimate会自动禁用动画 */
}

关键提醒：永远不要设置

disrespectUserMotionPreference: true

——这会违反无障碍标准。

—

官方文档

—

官方网站：https://auto-animate.formkit.com
GitHub仓库：https://github.com/formkit/auto-animate
npm包：https://www.npmjs.com/package/@formkit/auto-animate
React文档：https://auto-animate.formkit.com/react
视频教程：Laracasts视频（参考README）

—

验证通过的包版本（2025-11-07）

—

json

{
  "dependencies": {
    "@formkit/auto-animate": "^0.9.0"
  },
  "devDependencies": {
    "react": "^19.2.0",
    "vite": "^6.0.0"
  }
}

—

生产环境验证示例

—

本方案基于生产环境测试：

包体积：3.28 KB压缩后
配置时间：2分钟（对比Motion的15分钟）
错误数：0（已预防所有10个已知问题）
兼容性：✅ 支持Vite、Tailwind v4、Cloudflare Workers、React 19

测试场景覆盖：

✅ 筛选/排序列表
✅ 手风琴组件
✅ 提示通知
✅ 表单验证消息
✅ SSR/Cloudflare Workers
✅ 无障碍支持（prefers-reduced-motion）

—

故障排查

—

问题：动画不生效

—

解决方案：检查以下常见问题：

父元素是否始终在DOM中？（非条件渲染）
列表项是否有唯一稳定的key？
ref是否绑定到动画子元素的直接父元素？

—

问题：SSR/Next.js报错

—

解决方案：使用动态导入：

tsx

useEffect(() => {
  if (typeof window !== "undefined") {
    import("@formkit/auto-animate").then(({ default: autoAnimate }) => {
      autoAnimate(parent);
    });
  }
}, [parent]);

—

问题：元素闪烁而非平滑动画

—

解决方案：添加唯一key：使用

key={item.id}

而非

key={index}

—

问题：Flexbox宽度异常

—

解决方案：使用明确宽度代替

flex-grow: 1

—

问题：表格行不动画

—

解决方案：将ref绑定到

<tbody>

，而非单个

<tr>

元素

—

完整配置检查清单

—

已安装
```
@formkit/auto-animate@0.9.0
```
使用React 19+（或Vue/Svelte）
已为父元素添加ref
父元素始终保持渲染（非条件渲染）
列表项有唯一稳定的key
已测试
```
prefers-reduced-motion
```
场景
SSR场景已兼容（Cloudflare Workers/Next.js）
无Flexbox宽度问题
开发服务器运行无错误
生产构建成功

有问题？

查看
```
templates/
```
中的可用示例
查看
```
references/auto-animate-vs-motion.md
```
进行库对比
查看
```
references/ssr-patterns.md
```
获取SSR兼容方案
查看官方文档：https://auto-animate.formkit.com
查看GitHub issues：https://github.com/formkit/auto-animate/issues

是否可用于生产环境？ ✅ 是的——拥有13.6k星标，维护活跃，无任何依赖。",

auto-animate

Original

Translation

AutoAnimate

AutoAnimate

Quick Start (2 Minutes)

快速开始（2分钟）

1. Install AutoAnimate

1. 安装AutoAnimate

2. Add to Your Component

2. 在组件中引入

3. Use in Production (SSR-Safe)

3. 生产环境使用（SSR兼容）

Known Issues Prevention

已知问题预防

Issue #1: SSR/Next.js Import Errors

问题1：SSR/Next.js导入错误

Issue #2: Conditional Parent Rendering

问题2：父元素条件渲染

Issue #3: Missing Unique Keys

问题3：缺少唯一Key

Issue #4: Flexbox Width Issues

问题4：Flexbox宽度问题

Issue #5: Table Row Display Issues

问题5：表格行显示异常

Issue #6: Jest Testing Errors

问题6：Jest测试错误

Issue #7: esbuild Compatibility

问题7：esbuild兼容性问题

Issue #8: CSS Position Side Effects

问题8：CSS定位副作用

Issue #9: Vue/Nuxt Registration Errors

问题9：Vue/Nuxt注册错误

Issue #10: Angular ESM Issues

问题10：Angular ESM问题

When to Use AutoAnimate vs Motion

AutoAnimate与Motion的使用场景对比

Use AutoAnimate When:

优先选择AutoAnimate的场景：

Use Motion When:

优先选择Motion的场景：

Critical Rules

核心规则

Always Do

必须遵守

Never Do

禁止操作

Configuration

配置选项

Using Bundled Resources

配套资源使用

Templates (templates/)

模板文件（templates/）

References (references/)

参考文档（references/）

Scripts (scripts/)

脚本文件（scripts/）

Cloudflare Workers Compatibility

Cloudflare Workers兼容性

Accessibility

无障碍支持

Official Documentation

官方文档

Package Versions (Verified 2025-11-07)

验证通过的包版本（2025-11-07）

Production Example

生产环境验证示例

Troubleshooting

故障排查

Problem: Animations not working

问题：动画不生效

Problem: SSR/Next.js errors

问题：SSR/Next.js报错

Problem: Items flash instead of animating

问题：元素闪烁而非平滑动画

Problem: Flexbox width issues

问题：Flexbox宽度异常

Problem: Table rows don't animate

快速开始（2分钟）

1. 安装AutoAnimate