/auto-animate

name: auto-animate
description: "AutoAnimate (@formkit/auto-animate) zero-config animations for React. Use for list transitions, accordions, toasts, or encountering SSR errors, animation libraries complexity."

metadata:
  keywords:
    - auto-animate
    - "@formkit/auto-animate"
    - formkit
    - zero-config animation
    - automatic animations
    - drop-in animation
    - list animations
    - accordion animation
    - toast animation
    - form validation animation
    - lightweight animation
    - 2kb animation
    - prefers-reduced-motion
    - accessible animations
    - vite react animation
    - cloudflare workers animation
    - ssr safe animation

license: MIT

AutoAnimate

**Status**: Production Ready ✅ **Last Updated**: 2026-08-03 **Dependencies**: None (works with any React setup) **Latest Versions**: @formkit/auto-animate@0.10.0

---

Quick Start (2 Minutes)

1. Install AutoAnimate

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

2. Add to Your Component

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

3. Use in Production (SSR-Safe)

For Cloudflare Workers or Next.js:

// 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;
}

---

Known Issues Prevention

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**:

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

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

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

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

---

When to Use AutoAnimate vs Motion

Use AutoAnimate When:

• ✅ 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

Use Motion When:

• ✅ 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.

---

Critical Rules

Always Do

✅ **Use unique, sta