Provides SSR-safe patterns and fixes for @formkit/auto-animate errors in React, Vue, Solid, Svelte for animating lists, accordions, toasts with prefers-reduced-motion support.
From evolv3ainpx claudepluginhub evolv3ai/claude-skills-archive --plugin projectThis skill uses the workspace's default tool permissions.
README.mdassets/example-template.txtreferences/auto-animate-vs-motion.mdreferences/css-conflicts.mdreferences/example-reference.mdreferences/ssr-patterns.mdscripts/example-script.shscripts/init-auto-animate.shtemplates/accordion.tsxtemplates/filter-sort-list.tsxtemplates/form-validation.tsxtemplates/react-basic.tsxtemplates/react-typescript.tsxtemplates/toast-notifications.tsxtemplates/vite-ssr-safe.tsxGuides Next.js Cache Components and Partial Prerendering (PPR) with cacheComponents enabled. Implements 'use cache', cacheLife(), cacheTag(), revalidateTag(), static/dynamic optimization, and cache debugging.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
Guides idea refinement into designs: explores context, asks questions one-by-one, proposes approaches, presents sections for approval, writes/review specs before coding.
Package: @formkit/auto-animate@0.9.0 (current) Frameworks: React, Vue, Solid, Svelte, Preact Last Updated: 2026-01-21
// 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;
}
Why this matters: Prevents Issue #1 (SSR/Next.js import errors). AutoAnimate uses DOM APIs not available on server.
This skill prevents 15 documented issues:
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)
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:
React Pattern:
// ❌ Wrong
{showList && <ul ref={parent}>...</ul>}
// ✅ Correct
<ul ref={parent}>{showList && items.map(...)}</ul>
Vue.js Pattern:
<!-- ❌ Wrong - parent conditional -->
<ul v-if="showList" ref="parent">
<li v-for="item in items" :key="item.id">{{ item.text }}</li>
</ul>
<!-- ✅ Correct - children conditional -->
<ul ref="parent">
<li v-if="showList" v-for="item in items" :key="item.id">
{{ item.text }}
</li>
</ul>
Source: React Issue #8, Vue Issue #193
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})
Error: Elements snap to width instead of animating smoothly, or container shakes on remove
Source: Official docs, Issue #212
Why It Happens: flex-grow: 1 waits for surrounding content, causing timing issues
Prevention: Use explicit width instead of flex-grow for animated elements
// ❌ Wrong - causes shaking
<ul ref={parent} style={{ display: 'flex' }}>
{items.map(item => (
<li key={item.id} style={{ flex: '1 1 auto' }}>{item.text}</li>
))}
</ul>
// ✅ Correct - fixed sizes
<ul ref={parent} style={{ display: 'flex', gap: '1rem' }}>
{items.map(item => (
<li
key={item.id}
style={{ minWidth: '200px', maxWidth: '200px' }}
>
{item.text}
</li>
))}
</ul>
Maintainer Note: justin-schroeder confirmed fixed sizes are required for flex containers
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
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
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
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
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/)
Nuxt 3 Note: Requires v0.8.2+ (April 2024). Earlier versions have ESM import issues fixed by Daniel Roe. See Issue #199
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
Error: Child animations don't work in React 19 StrictMode Source: https://github.com/formkit/auto-animate/issues/232 Why It Happens: StrictMode calls useEffect twice, triggering autoAnimate initialization twice Prevention: Use ref to track initialization
// ❌ Wrong - breaks in StrictMode
const [parent] = useAutoAnimate();
// ✅ Correct - prevents double initialization
const [parent] = useAutoAnimate();
const initialized = useRef(false);
useEffect(() => {
if (initialized.current) return;
initialized.current = true;
}, []);
Note: React 19 enables StrictMode by default in development. This affects all React 19+ projects.
Error: Animations broken when list is outside viewport Source: https://github.com/formkit/auto-animate/issues/222 Why It Happens: Chrome may not run Animation API for off-screen elements Prevention: Ensure parent is visible before applying autoAnimate
const isInViewport = (element) => {
const rect = element.getBoundingClientRect();
return rect.top >= 0 && rect.bottom <= window.innerHeight;
};
useEffect(() => {
if (parent.current && isInViewport(parent.current)) {
autoAnimate(parent.current);
}
}, [parent]);
Error: Removed items overlay other items during fade out Source: https://github.com/formkit/auto-animate/issues/231 Why It Happens: Exit animation maintains z-index, covering active content Prevention: Add explicit z-index handling
// CSS workaround
<style>{`
[data-auto-animate-target] {
z-index: -1 !important;
}
`}</style>
Error: Calling enable(false) doesn't prevent animations during drag Source: https://github.com/formkit/auto-animate/issues/215 Why It Happens: Disable doesn't work reliably mid-drag Prevention: Conditionally remove ref during drag
const [isDragging, setIsDragging] = useState(false);
const [parent] = useAutoAnimate();
return (
<ul ref={isDragging ? null : parent}>
{/* items */}
</ul>
);
Error: Items animate from wrong position after parent transform Source: https://github.com/formkit/auto-animate/issues/227 Why It Happens: Items remember original position before transform Prevention: Delay autoAnimate until transform completes
useEffect(() => {
if (showList && parent.current) {
setTimeout(() => {
autoAnimate(parent.current);
}, 300); // Match CSS transition duration
}
}, [showList]);
✅ 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
❌ 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
Note: AutoAnimate respects prefers-reduced-motion automatically (never disable this).
Note: These tips come from community discussions. Verify against your version.
Source: Issue #230 | Confidence: MEDIUM Applies to: v0.8.2+
Tests may freeze for ~10 seconds when package is mocked. Add ResizeObserver mock:
// jest.setup.js
global.ResizeObserver = jest.fn().mockImplementation(() => ({
observe: jest.fn(),
unobserve: jest.fn(),
disconnect: jest.fn(),
}));
// __mocks__/@formkit/auto-animate.js
const autoAnimate = jest.fn(() => () => {});
const useAutoAnimate = jest.fn(() => [null, jest.fn(), jest.fn()]);
module.exports = { default: autoAnimate, useAutoAnimate };
Source: Issue #180 | Confidence: LOW Applies to: All versions
For long-lived SPAs, ensure proper cleanup:
useEffect(() => {
const cleanup = autoAnimate(parent.current);
return () => cleanup && cleanup();
}, []);
// useAutoAnimate hook handles cleanup automatically
const [parent] = useAutoAnimate(); // Preferred
Latest: @formkit/auto-animate@0.9.0 (Sept 5, 2025)
Recent Releases:
{
"dependencies": {
"@formkit/auto-animate": "^0.9.0"
}
}
Framework Compatibility: React 18+, Vue 3+, Solid, Svelte, Preact
Important: For Nuxt 3 users, v0.8.2+ is required. Earlier versions have ESM import issues
See bundled resources:
templates/ - Copy-paste examples (SSR-safe, accordion, toast, forms)references/ - CSS conflicts, SSR patterns, library comparisons