auto-animate

```tsx

// Use client-only import to prevent SSR errors

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;

}

```

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

---

This skill prevents 10+ 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:

```tsx

// ❌ Wrong

{showList &&

...

// ✅ Correct

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

```

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 Issues

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

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

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

---

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 &&

}

❌ 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).

---

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

```json

{

"dependencies": {

"@formkit/auto-animate": "^0.9.0"

}

}

```

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

---

• 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

---

See bundled resources:

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