auto-animate

AutoAnimate

Status: Production Ready ✅ Last Updated: 2026-08-03 Dependencies: None (works with any React setup) Latest Versions: @formkit/[email protected]

---

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>