AutoAnimate - Error Prevention Guide
Package: @formkit/[email protected] (current)
Frameworks: React, Vue, Solid, Svelte, Preact
Last Updated: 2026-01-21
SSR-Safe Pattern (Critical for Cloudflare Workers/Next.js)
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;
}
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:
{showList && <ul ref={parent}>...</ul>}
<ul ref={parent}>{showList && items.map(...)}</ul>
Vue.js Pattern:
<!-- ❌ Wrong - parent conditional -->
<ul v-if="showList" ref="parent">
<li v-for="item in items" :key="item.id">{{ item.text }}</li>
</ul>
<!-- ✅ Correct - children conditional -->
<ul ref="parent">
<li v-if="showList" v-for="item in items" :key="item.id">
{{ item.text }}
</li>
</ul>
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
<ul ref={parent} style={{ display: 'flex' }}>
{items.map(item => (
<li key={item.id} style={{ flex: '1 1 auto' }}>{item.text}</li>
))}
</ul>
<ul ref={parent} style={{ display: 'flex', gap: '1rem' }}>
{items.map(item => (
<li
key={item.id}
style={{ minWidth: '200px', maxWidth: '200px' }}
>
{item.text}
</li>
))}
</ul>
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
const [parent] = useAutoAnimate();
const [parent] = useAutoAnimate();
const initialized = useRef(false);
useEffect(() => {
if (initialized.current) return;
initialized.current = true;
}, []);
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
const isInViewport = (element) => {
const rect = element.getBoundingClientRect();
<
