Skip to main content
skill CX Codex

auto-animate — Claude Code skill: what it does, how to install

A skill that shows how to wire up @formkit/auto-animate in React for lists, accordions and toasts. Animations with zero config, 3.28 KB gzipped.

MIT 257 installs ★ 250 updated 2026-10-20

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add secondsky/claude-skills --skill auto-animate -a claude-code
Open on GitHub

What auto-animate does

When you add or remove list items, AutoAnimate slides them smoothly. Setup is one line: import the useAutoAnimate hook, attach the ref to a parent, done. Stable keys on children are required (key={item.id}), parent must stay in the DOM — conditional rendering breaks animations.

The skill covers ten common issues: import errors in Next.js and Cloudflare Workers (solved with client-side dynamic import), conflicts with display: table-row (apply to <tbody> instead), bugs with flex-grow (use explicit width). Respects prefers-reduced-motion out of the box.

Inside are examples for Vite, SSR, Jest, esbuild, a comparison table with Motion, and guidelines for when AutoAnimate suffices versus when you need a full choreography and gesture library.

What it helps with

  • animate a list when adding or removing items
  • fix AutoAnimate SSR errors in Next.js
  • apply animations to accordions or toasts without setup
  • stop element flicker during reordering
  • swap Motion for a lighter animation library

Example prompts for the agent

  • Wire up @formkit/auto-animate to a task list so items fade in and out smoothly
  • Fix the AutoAnimate import error in Next.js using client-side dynamic import
  • Show me how to apply AutoAnimate to a table without breaking display: table-row

How to install auto-animate

1Skills CLI (Vercel)

npx skills add secondsky/claude-skills --skill auto-animate -a claude-code

2Manually: put the files in place

~/.claude/skills/auto-animate/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/auto-animate/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about auto-animate

How to install auto-animate in Claude Code?

Run npx skills add secondsky/claude-skills --skill auto-animate -a claude-code, the skill lands in ~/.claude/skills/auto-animate/SKILL.md.

What does auto-animate do?

The skill teaches you to integrate @formkit/auto-animate for automatic list, accordion and toast animations in React. Solves SSR issues, display conflicts and missing keys.

Why doesn't AutoAnimate work in Next.js?

The library uses DOM APIs unavailable on the server. The skill provides a wrapper with client-side dynamic import to avoid import errors during server render.

Source text

SKILL.md · MIT
---
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/[email protected]

---

## Quick Start (2 Minutes)

### 1. Install AutoAnimate

```bash
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

```tsx
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:

```tsx
// 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**:
```tsx
// ❌ 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, 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 && <ul ref={parent}>}`
❌ **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

---

## Configuration

AutoAnimate is zero-config by default. Optional customization:

```tsx
import { useAutoAnimate } from "@formkit/auto-animate/react";

const [parent] = useAutoAnimate({
  duration: 250, // milliseconds (default: 250)
  easing: "ease-in-out", // CSS easing (default: "ease-in-out")
  // disrespectUserMotionPreference: false, // Keep false!
});
```

**Recommendation**: Use defaults unless you have specific design requirements.

---

## Using Bundled Resources

### Templates (templates/)

Copy-paste ready examples:

- `react-basic.tsx` - Simple list with add/remove/shuffle
- `react-typescript.tsx` - Typed setup with custom config
- `filter-sort-list.tsx` - Animated filtering and sorting
- `accordion.tsx` - Expandable sections
- `toast-notifications.tsx` - Fade in/out messages
- `form-validation.tsx` - Error messages animation
- `vite-ssr-safe.tsx` - Cloudflare Workers/SSR pattern

### References (references/)

- `auto-animate-vs-motion.md` - Decision guide for which to use
- `css-conflicts.md` - Flexbox, table, and position gotchas
- `ssr-patterns.md` - Next.js, Nuxt, Workers workarounds

### Scripts (scripts/)

- `init-auto-animate.sh` - Automated setup script

---

## Cloudflare Workers Compatibility

AutoAnimate works perfectly with Cloudflare Workers Static Assets:

✅ **Client-side only** - Runs in browser, not Worker runtime
✅ **No Node.js deps** - Pure browser code
✅ **Edge-friendly** - 3.28 KB gzipped
✅ **SSR-safe** - Use dynamic imports (see templates/)

**Vite Config**:
```typescript
export default defineConfig({
  plugins: [react(), cloudflare()],
  ssr: {
    external: ["@formkit/auto-animate"],
  },
});
```

---

## Accessibility

AutoAnimate respects `prefers-reduced-motion` **automatically**:

```css
/* User's system preference */
@media (prefers-reduced-motion: reduce) {
  /* AutoAnimate disables animations automatically */
}
```

**Critical**: Never set `disrespectUserMotionPreference: true` - this breaks accessibility.

---

## Official Documentation

- **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
- **Video Tutorial**: Laracasts video (see README)

---

## Package Versions (Verified 2026-08-03)

```json
{
  "dependencies": {
    "@formkit/auto-animate": "^0.10.0"
  },
  "devDependencies": {
    "react": "^19.2.0",
    "vite": "^7.3.0"
  }
}
```

---

## Production Example

This skill is based on production testing:

- **Bundle Size**: 3.28 KB gzipped
- **Setup Time**: 2 minutes (vs 15 min with Motion)
- **Errors**: 0 (all 10 known issues prevented)
- **Validation**: ✅ Works with Vite, Tailwind v4, Cloudflare Workers, React 19

**Tested Scenarios:**
- ✅ Filter/sort lists
- ✅ Accordion components
- ✅ Toast notifications
- ✅ Form validation messages
- ✅ SSR/Cloudflare Workers
- ✅ Accessibility (prefers-reduced-motion)

---

## Troubleshooting

### Problem: Animations not working
**Solution**: Check these common issues:
1. Is parent element always in DOM? (not conditional)
2. Do items have unique, stable keys?
3. Is ref attached to immediate parent of animated children?

### Problem: SSR/Next.js errors
**Solution**: Use dynamic import:
```tsx
useEffect(() => {
  if (typeof window !== "undefined") {
    import("@formkit/auto-animate").then(({ default: autoAnimate }) => {
      autoAnimate(parent);
    });
  }
}, [parent]);
```

### Problem: Items flash instead of animating
**Solution**: Add unique keys: `key={item.id}` not `key={index}`

### Problem: Flexbox width issues
**Solution**: Use explicit width instead of `flex-grow: 1`

### Problem: Table rows don't animate
**Solution**: Apply ref to `<tbody>`, not individual `<tr>` elements

---

## Complete Setup Checklist

- [ ] Installed `@formkit/[email protected]`
- [ ] Using React 19+ (or Vue/Svelte)
- [ ] Added ref to parent element
- [ ] Parent element always rendered (not conditional)
- [ ] List items have unique, stable keys
- [ ] Tested with `prefers-reduced-motion`
- [ ] SSR-safe if using Cloudflare Workers/Next.js
- [ ] No flexbox width issues
- [ ] Dev server runs without errors
- [ ] Production build succeeds

---

**Questions? Issues?**

1. Check `templates/` for working examples
2. Check `references/auto-animate-vs-motion.md` for library comparison
3. Check `references/ssr-patterns.md` for SSR workarounds
4. Check official docs: https://auto-animate.formkit.com
5. Check GitHub issues: https://github.com/formkit/auto-animate/issues

---

**Production Ready?** ✅ Yes - 13.6k stars, actively maintained, zero dependencies.

© secondsky · MIT · secondsky/claude-skills

Similar skills

All skills for Frontend and UI →

From the same set138

The whole set →
nextjs Skill for Next.js 16 and React 19.2 with App Router, Server Components, Server Actions, and caching patterns. Handles migration from version 15, async params errors, and Partial Prerendering setup. CX Codex +1 299installs feature-dev The feature-dev skill guides feature work through seven phases, from codebase discovery to review. Use it for multi-file changes and unclear architecture decisions. CX Codex +1 294installs cloudflare-nextjs The cloudflare-nextjs skill guides Next.js deployments to Cloudflare Workers with OpenNext. Use it to migrate a project or troubleshoot Workers-specific configuration and runtime issues. CX Codex +1 267installs cloudflare-turnstile cloudflare-turnstile is a Claude Code skill for adding Turnstile and checking tokens on the server. It activates for bot protection work, widget errors, and CSP or token validation failures. CX Codex +1 261installs base-ui-react base-ui-react is a Claude Code skill for building MUI Base UI interfaces, configuring accessible components and popup positioning, and migrating from Radix UI. CX Codex +1 259installs hono-routing hono-routing — a skill for building Hono APIs: routes, middleware, Zod or Valibot validation, RPC client with type inference. Covers 12 common errors and their solutions. CX Codex +1 256installs pinia-colada Brings Pinia Colada data fetching into Claude Code and other AI editors. Handles async state, query caching, SSR, and migration from TanStack Vue Query with useQuery and useMutation. CX Codex +1 253installs github-project-automation github-project-automation is a Claude Code skill for setting up GitHub Actions, repository templates, CodeQL, and Dependabot. It helps start projects and troubleshoot workflow YAML. CX Codex +1 1installs

Project sponsors

Companies that keep this analytics open