auto-animate
AutoAnimate (@formkit/auto-animate) zero-config animations for React. Use for list transitions, accordions, toasts, or encountering SSR errors, animation libraries complexity.
secondsky · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add secondsky/claude-skills --skill 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-motionautomatically - ✅ 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
阅读完整来源 ↗