AutoAnimate - Error Prevention Guide

Package: @formkit/auto-animate@0.9.0 (current)
Frameworks: React, Vue, Solid, Svelte, Preact
Last Updated: 2026-01-21

SSR-Safe Pattern (Critical for Cloudflare Workers/Next.js)

CODEBLOCK0

Why this matters: Prevents Issue #1 (SSR/Next.js import errors). AutoAnimate uses DOM APIs not available on server.

Known Issues Prevention (15 Documented Errors)

This skill prevents 15 documented issues:

Issue #1: SSR/Next.js Import Errors

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)

Issue #2: Conditional Parent Rendering

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:

React Pattern:
CODEBLOCK1

Vue.js Pattern:
CODEBLOCK2

Source: React Issue #8, Vue Issue #193

Issue #3: Missing Unique Keys

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})

Issue #4: Flexbox Width and Shaking Issues

Error: Elements snap to width instead of animating smoothly, or container shakes on remove Source: Official docs, Issue #212 Why It Happens: flex-grow: 1 waits for surrounding content, causing timing issues Prevention: Use explicit width instead of flex-grow for animated elements

CODEBLOCK3

Maintainer Note: justin-schroeder confirmed fixed sizes are required for flex containers

Issue #5: Table Row Display Issues

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

Issue #6: Jest Testing Errors

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

Issue #7: esbuild Compatibility

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

Issue #8: CSS Position Side Effects

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

Issue #9: Vue/Nuxt Registration Errors

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

Nuxt 3 Note: Requires v0.8.2+ (April 2024). Earlier versions have ESM import issues fixed by Daniel Roe. See Issue #199

Issue #10: Angular ESM Issues

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

Issue #11: React 19 StrictMode Double-Call Bug

Error: Child animations don't work in React 19 StrictMode Source: https://github.com/formkit/auto-animate/issues/232 Why It Happens: StrictMode calls useEffect twice, triggering autoAnimate initialization twice Prevention: Use ref to track initialization

CODEBLOCK4

Note: React 19 enables StrictMode by default in development. This affects all React 19+ projects.

Issue #12: Broken Animation Outside Viewport

Error: Animations broken when list is outside viewport Source: https://github.com/formkit/auto-animate/issues/222 Why It Happens: Chrome may not run Animation API for off-screen elements Prevention: Ensure parent is visible before applying autoAnimate

CODEBLOCK5

Issue #13: Deleted Elements Overlay Existing Content

Error: Removed items overlay other items during fade out Source: https://github.com/formkit/auto-animate/issues/231 Why It Happens: Exit animation maintains z-index, covering active content Prevention: Add explicit z-index handling

CODEBLOCK6

Issue #14: Cannot Disable During Drag & Drop

Error: Calling enable(false) doesn't prevent animations during drag Source: https://github.com/formkit/auto-animate/issues/215 Why It Happens: Disable doesn't work reliably mid-drag Prevention: Conditionally remove ref during drag

CODEBLOCK7

Issue #15: CSS Transform Parent Position Bug

Error: Items animate from wrong position after parent transform Source: https://github.com/formkit/auto-animate/issues/227 Why It Happens: Items remember original position before transform Prevention: Delay autoAnimate until transform completes

CODEBLOCK8

Critical Rules (Error Prevention)

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

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

Note: AutoAnimate respects prefers-reduced-motion automatically (never disable this).

Community Tips (Community-Sourced)

Note: These tips come from community discussions. Verify against your version.

Tip: Prevent Test Freezing with Mocked Package

Source: Issue #230 | Confidence: MEDIUM
Applies to: v0.8.2+

Tests may freeze for ~10 seconds when package is mocked. Add ResizeObserver mock:

CODEBLOCK9

Tip: Memory Leak Prevention

Source: Issue #180 | Confidence: LOW
Applies to: All versions

For long-lived SPAs, ensure proper cleanup:

CODEBLOCK10

Package Versions

Latest: @formkit/auto-animate@0.9.0 (Sept 5, 2025)

Recent Releases:

- v0.9.0 (Sept 5, 2025) - Current stable
v0.8.2 (April 10, 2024) - Fixed Nuxt 3 ESM imports, ResizeObserver guard

CODEBLOCK11

Framework Compatibility: React 18+, Vue 3+, Solid, Svelte, Preact

Important: For Nuxt 3 users, v0.8.2+ is required. Earlier versions have ESM import issues

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

Templates & References

See bundled resources:

- templates/ - Copy-paste examples (SSR-safe, accordion, toast, forms)
INLINECODE14 - CSS conflicts, SSR patterns, library comparisons

AutoAnimate - 错误预防指南

包名: @formkit/auto-animate@0.9.0 (当前版本)
框架: React, Vue, Solid, Svelte, Preact
最后更新: 2026-01-21

SSR安全模式 (对Cloudflare Workers/Next.js至关重要)

tsx
// 使用客户端专用导入以防止SSR错误
import { useState, useEffect } from react;

export function useAutoAnimateSafe() {
const [parent, setParent] = useState(null);

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

return [parent, setParent] as const;
}

为何重要: 防止问题#1 (SSR/Next.js导入错误)。AutoAnimate使用服务器上不可用的DOM API。

已知问题预防 (15个已记录错误)

此技能可预防 15 个已记录问题：

问题#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无法附加到不存在的元素预防:

React模式:
tsx
// ❌ 错误
{showList &&

...}

// ✅ 正确

{showList && items.map(...)}

Vue.js模式:
vue

{{ item.text }}

{{ item.text }}

来源: React 问题#8, Vue 问题#193

问题#3: 缺少唯一键

错误: 项目动画不正确或闪烁来源: 官方文档原因: React无法追踪哪些项目发生了变化预防: 始终使用唯一、稳定的键 (key={item.id})

问题#4: Flexbox宽度和抖动问题

错误: 元素直接跳转到宽度而非平滑动画，或容器在移除时抖动来源: 官方文档, 问题#212 原因: flex-grow: 1等待周围内容，导致时序问题预防: 对动画元素使用显式宽度而非flex-grow

tsx
// ❌ 错误 - 导致抖动

{item.text}

// ✅ 正确 - 固定尺寸

key={item.id}
style={{ minWidth: 200px, maxWidth: 200px }}
>
{item.text}

))}

维护者注: justin-schroeder确认flex容器需要固定尺寸

问题#5: 表格行显示问题

错误: 移除行时表格结构被破坏来源: https://github.com/formkit/auto-animate/issues/7 原因: display: table-row与动画冲突预防: 应用到而非单独的行，或使用基于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/)

Nuxt 3注: 需要v0.8.2+ (2024年4月)。早期版本有Daniel Roe修复的ESM导入问题。参见问题#199

问题#10: Angular ESM问题

错误: 构建失败，提示仅ESM包来源: https://github.com/formkit/auto-animate/issues/72 原因: CommonJS构建环境预防: 为Angular包格式配置ng-packagr

问题#11: React 19 StrictMode双重调用错误

错误: 子元素动画在React 19 StrictMode中不工作来源: https://github.com/formkit/auto-animate/issues/232 原因: StrictMode调用useEffect两次，触发autoAnimate初始化两次预防: 使用ref追踪初始化

tsx
// ❌ 错误 - 在StrictMode中失效
const [parent] = useAutoAnimate();

// ✅ 正确 - 防止双重初始化
const [parent] = useAutoAnimate();
const initialized = useRef(false);

useEffect(() => {
if (initialized.current) return;
initialized.current = true;
}, []);

注: React 19在开发模式下默认启用StrictMode。这影响所有React 19+项目。

问题#12: 视口外动画失效

错误: 列表在视口外时动画失效来源: https://github.com/formkit/auto-animate/issues/222 原因: Chrome可能不为屏幕外元素运行动画API 预防: 在应用autoAnimate前确保父元素可见

tsx
const isInViewport = (element) => {
const rect = element.getBoundingClientRect();
return rect.top >= 0 && rect.bottom <= window.innerHeight;
};

useEffect(() => {
if (parent.current && isInViewport(parent.current)) {
autoAnimate(parent.current);
}
}, [parent]);

问题#13: 已删除元素覆盖现有内容

错误: 移除的项目在淡出期间覆盖其他项目来源: https://github.com/formkit/auto-animate/issues/231 原因: 退出动画保持z-index，覆盖活动内容预防: 添加显式z-index处理

tsx
// CSS解决方案

问题#14: 拖放期间无法禁用

错误: 调用enable(false)在拖放期间不阻止动画来源: https://github.com/formkit/auto-animate/issues/215 原因: 在拖放过程中禁用不可靠预防: 在拖放期间有条件地移除ref

tsx
const [isDragging, setIsDragging] = useState(false);
const [parent] = useAutoAnimate();

return (

项目

);

问题#15: CSS变换父元素位置错误

错误: 父元素变换后项目从错误位置开始动画来源: https://github.com/formkit/auto-animate/issues/227 原因: 项目记住变换前的原始位置预防: 延迟autoAnimate直到变换完成

tsx
useEffect(() => {

auto-animate自动动画

auto-animate

AutoAnimate - Error Prevention Guide

SSR-Safe Pattern (Critical for Cloudflare Workers/Next.js)

Known Issues Prevention (15 Documented Errors)

Issue #1: SSR/Next.js Import Errors

Issue #2: Conditional Parent Rendering

Issue #3: Missing Unique Keys

Issue #4: Flexbox Width and Shaking Issues

Issue #5: Table Row Display Issues

Issue #6: Jest Testing Errors

Issue #7: esbuild Compatibility

Issue #8: CSS Position Side Effects

Issue #9: Vue/Nuxt Registration Errors

Issue #10: Angular ESM Issues

Issue #11: React 19 StrictMode Double-Call Bug

Issue #12: Broken Animation Outside Viewport

Issue #13: Deleted Elements Overlay Existing Content

Issue #14: Cannot Disable During Drag & Drop

Issue #15: CSS Transform Parent Position Bug

Critical Rules (Error Prevention)

Always Do

Never Do

Community Tips (Community-Sourced)

Tip: Prevent Test Freezing with Mocked Package

Tip: Memory Leak Prevention

Package Versions

Official Documentation

Templates & References

AutoAnimate - 错误预防指南

SSR安全模式 (对Cloudflare Workers/Next.js至关重要)

已知问题预防 (15个已记录错误)

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

问题#2: 条件性父元素渲染

问题#3: 缺少唯一键

问题#4: Flexbox宽度和抖动问题

问题#5: 表格行显示问题

问题#6: Jest测试错误

问题#7: esbuild兼容性

问题#8: CSS定位副作用

问题#9: Vue/Nuxt注册错误

问题#10: Angular ESM问题

问题#11: React 19 StrictMode双重调用错误

问题#12: 视口外动画失效

问题#13: 已删除元素覆盖现有内容

问题#14: 拖放期间无法禁用

问题#15: CSS变换父元素位置错误

标签

通过对话安装

方式一：安装 SkillHub 和技能

方式二：设置 SkillHub 为优先技能安装源

通过命令行安装

下载

相关推荐

self-improvement

self-improvement

self-improvement

self-improvement