AutoAnimate은(는) 무엇을 하나요?
상태: 프로덕션 준비 완료 ✅ 마지막 업데이트: 2025-11-07 의존성: 없음 (모든 React 환경에서 동작) 최신 버전: @formkit/[email protected]
빠른 시작 (2분)
1. AutoAnimate 설치
bun add @formkit/auto-animate
왜 중요한가요?
- 번들 크기 3.28KB (Motion은 22KB)
- 의존성 제로
- 프레임워크에 구애받지 않음 (React, Vue, Svelte, 바닐라 JS)
2. 컴포넌트에 추가
import { useAutoAnimate } from "@formkit/auto-animate/react";
export function MyList() {
const [parent] = useAutoAnimate(); // 1. ref 획득
return (
<ul ref={parent}> {/* 2. 부모 요소에 연결 */}
{items.map(item => (
<li key={item.id}>{item.text}</li> {/* 3. 끝! */}
))}
</ul>
);
}
중요:
- ✅ 항상 리스트 아이템에 유니크하고 안정적인
key를 사용하세요. - ✅ 부모 요소는 항상 렌더링되어야 합니다 (조건부 렌더링 금지).
- ✅ AutoAnimate는
prefers-reduced-motion을 자동으로 존중합니다. - ✅ 추가, 제거, 재정렬 모두에서 동작합니다.
3. 프로덕션에서 사용 (SSR-안전)
Cloudflare Workers 또는 Next.js에서 사용:
// SSR 오류를 방지하기 위해 클라이언트 전용 import 사용
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;
}
알려진 문제 예방
이 스킬은 10개 이상의 문서화된 문제를 예방합니다.
문제 #1: SSR/Next.js Import 오류
오류: "Can't import the named export 'useEffect' from non EcmaScript module"
출처: https://github.com/formkit/auto-animate/issues/55
원인: AutoAnimate는 서버에서 사용할 수 없는 DOM API를 사용합니다.
예방: 동적 임포트 사용 (templates/vite-ssr-safe.tsx 참고)
문제 #2: 조건부 부모 렌더링
오류: 부모 요소가 조건부로 렌더링될 때 애니메이션이 동작하지 않음 출처: https://github.com/formkit/auto-animate/issues/8 원인: 존재하지 않는 요소에는 ref를 연결할 수 없습니다. 예방:
// ❌ 잘못된 방법
{showList && <ul ref={parent}>...</ul>}
// ✅ 올바른 방법
<ul ref={parent}>{showList && items.map(...)}</ul>
문제 #3: 유니크 키 누락
오류: 아이템이 올바르게 애니메이션되지 않거나 깜빡임
출처: 공식 문서
원인: React가 변경된 아이템을 추적할 수 없습니다.
예방: 항상 유니크하고 안정적인 key 사용 (key={item.id})
문제 #4: 플렉스박스 폭 이슈
오류: 요소가 부드럽게 애니메이션되지 않고 폭이 즉시 변경됨
출처: 공식 문서
원인: flex-grow: 1이 주변 콘텐츠를 기다립니다.
예방: 애니메이션 요소에 flex-grow 대신 명시적인 폭 사용
문제 #5: 테이블 행 표시 이슈
오류: 행을 제거할 때 테이블 구조가 깨짐
출처: https://github.com/formkit/auto-animate/issues/7
원인: display: table-row가 애니메이션과 충돌합니다.
예방: 개별 행 대신 <tbody>에 적용하거나 div 기반 레이아웃 사용
문제 #6: Jest 테스트 오류
오류: "Cannot find module '@formkit/auto-animate/react'"
출처: https://github.com/formkit/auto-animate/issues/29
원인: Jest가 ESM 내보내기를 올바르게 해석하지 못합니다.
예방: jest.config.js에서 moduleNameMapper 설정
문제 #7: esbuild 호환성
오류: "Path '.' not exported by package" 출처: https://github.com/formkit/auto-animate/issues/36 원인: ESM/CommonJS 조건 불일치 예방: esbuild가 ESM 모듈을 올바르게 처리하도록 설정
문제 #8: CSS position 부작용
오류: AutoAnimate 추가 후 레이아웃이 깨짐
출처: 공식 문서
원인: 부모 요소가 자동으로 position: relative를 획득합니다.
예방: CSS에서 position 변경을 고려하거나 명시적으로 설정
문제 #9: Vue/Nuxt 등록 오류
오류: "Failed to resolve directive: auto-animate" 출처: https://github.com/formkit/auto-animate/issues/43 원인: 플러그인이 올바르게 등록되지 않았습니다. 예방: Vue/Nuxt 설정에서 적절한 플러그인 설정 (참고 문서 확인)
문제 #10: Angular ESM 이슈
오류: "ESM-only package"로 인한 빌드 실패
출처: https://github.com/formkit/auto-animate/issues/72
원인: CommonJS 빌드 환경
예방: Angular 패키지 형식에 맞게 ng-packagr 설정
AutoAnimate vs Motion 사용 시점
AutoAnimate를 사용해야 할 때:
- ✅ 간단한 리스트 전환 (추가/제거/정렬)
- ✅ 아코디언 펼치기/접기
- ✅ 토스트 알림 페이드 인/아웃
- ✅ 폼 검증 메시지 표시/사라짐
- ✅ 제로 설정 선호
- ✅ 작은 번들 크기가 중요할 때 (3.28KB)
- ✅ 기존 또는 서드파티 코드에 적용
- ✅ "충분히 좋은" 애니메이션 허용 가능
Motion을 사용해야 할 때:
- ✅ 복잡하게 연출된 애니메이션
- ✅ 제스처 제어 (드래그, 스와이프, 호버)
- ✅ 스크롤 기반 애니메이션
- ✅ 스프링 물리 애니메이션
- ✅ SVG 경로 애니메이션
- ✅ 키프레임 제어 필요
- ✅ 애니메이션 변형/오케스트레이션
- ✅ 사용자 정의 이징 곡선
경험 법칙: 90%의 경우 AutoAnimate를 사용하고, 영웅/인터랙티브 애니메이션에는 Motion을 사용하세요.
핵심 규칙
항상 지켜야 할 것
✅ 유니크하고 안정적인 키 사용 - key={item.id} (not key={index})
✅ 부모 요소를 DOM에 유지 - 부모 ref 요소는 항상 렌더링
✅ SSR에서는 클라이언트 전용 - 서버 환경에서는 동적 임포트
✅ 접근성 존중 - disrespectUserMotionPreference: false 유지
✅ 모션 비활성화 상태에서 테스트 - 애니메이션 없이도 UI가 정상 동작하는지 확인
✅ 명시적 폭 사용 - 애니메이션 요소에 flex-grow 사용 금지
✅ 테이블은 tbody에 적용 - 개별 행이 아닌 <tbody>에 적용
절대 하지 말아야 할 것
❌ 조건부 부모 - {show && <ul ref={parent}>}
❌ 인덱스를 키로 사용 - key={index}는 애니메이션을 깨뜨림
❌ SSR 무시 - Cloudflare Workers/Next.js에서 오류 발생
❌ 애니메이션 강제 - disrespectUserMotionPreference: true는 접근성을 해침
❌ 테이블에 직접 애니메이션 - <tbody> 또는 div 기반 레이아웃 사용
❌ 유니크 키 생략 - 올바른 애니메이션에 필수
❌ 복잡한 애니메이션 - Motion 사용
설정
AutoAnimate는 기본적으로 제로 설정입니다. 선택적 사용자 지정:
import { useAutoAnimate } from "@formkit/auto-animate/react";
const [parent] = useAutoAnimate({
duration: 250, // 밀리초 (기본값: 250)
easing: "ease-in-out", // CSS 이징 (기본값: "ease-in-out")
// disrespectUserMotionPreference: false, // false 유지!
});
권장사항: 특정 디자인 요구사항이 없는 한 기본값을 사용하세요.
번들 리소스 사용
템플릿 (templates/)
복사-붙여넣기로 바로 사용 가능한 예제:
react-basic.tsx- 추가/제거/섞기가 있는 간단한 리스트react-typescript.tsx- 타입이 지정된 설정 및 사용자 설정filter-sort-list.tsx- 애니메이션 필터링 및 정렬accordion.tsx- 확장 가능한 섹션toast-notifications.tsx- 메시지 페이드 인/아웃form-validation.tsx- 오류 메시지 애니메이션vite-ssr-safe.tsx- Cloudflare Workers/SSR 패턴
참고 자료 (references/)
auto-animate-vs-motion.md- 사용 결정 가이드css-conflicts.md- 플렉스박스, 테이블, position 문제ssr-patterns.md- Next.js, Nuxt, Workers 우회 방법
스크립트 (scripts/)
init-auto-animate.sh- 자동 설정 스크립트
Cloudflare Workers 호환성
AutoAnimate는 Cloudflare Workers 정적 자산과 완벽하게 동작합니다:
✅ 클라이언트 전용 - 브라우저에서 실행, Worker 런타임 아님 ✅ Node.js 의존성 없음 - 순수 브라우저 코드 ✅ 엣지 친화적 - 3.28KB gzip ✅ SSR-안전 - 동적 임포트 사용 (템플릿 참고)
Vite 설정:
export default defineConfig({
plugins: [react(), cloudflare()],
ssr: {
external: ["@formkit/auto-animate"],
},
});
접근성
AutoAnimate는 prefers-reduced-motion을 자동으로 존중합니다:
/* 사용자의 시스템 환경 설정 */
@media (prefers-reduced-motion: reduce) {
/* AutoAnimate가 자동으로 애니메이션을 비활성화합니다 */
}
중요: disrespectUserMotionPreference: true를 절대 설정하지 마세요. 접근성을 해칩니다.
공식 문서
- 공식 사이트: https://auto-animate.formkit.com
- GitHub: https://github.com/formkit/auto-animate
- npm: https://www.npmjs.com/package/@formkit/auto-animate
- React 문서: https://auto-animate.formkit.com/react
- 비디오 튜토리얼: Laracasts 비디오 (README 참고)
패키지 버전 (2025-11-07 확인)
{
"dependencies": {
"@formkit/auto-animate": "^0.9.0"
},
"devDependencies": {
"react": "^19.2.0",
"vite": "^6.0.0"
}
}
프로덕션 예제
이 스킬은 프로덕션 테스트를 기반으로 합니다:
- 번들 크기: 3.28KB gzip
- 설정 시간: 2분 (Motion은 15분)
- 오류: 0 (모든 10개의 알려진 문제 예방)
- 검증: ✅ Vite, Tailwind v4, Cloudflare Workers, React 19에서 동작 확인
테스트된 시나리오:
- ✅ 필터/정렬 리스트
- ✅ 아코디언 컴포넌트
- ✅ 토스트 알림
- ✅ 폼 검증 메시지
- ✅ SSR/Cloudflare Workers
- ✅ 접근성 (prefers-reduced-motion)
문제 해결
문제: 애니메이션이 동작하지 않음
해결 방법: 다음 일반적인 문제를 확인하세요.
- 부모 요소가 항상 DOM에 있나요? (조건부 렌더링 금지)
- 아이템에 유니크하고 안정적인 키가 있나요?
- ref가 애니메이션 대상의 직계 부모에 연결되어 있나요?
문제: SSR/Next.js 오류
해결 방법: 동적 임포트 사용:
useEffect(() => {
if (typeof window !== "undefined") {
import("@formkit/auto-animate").then(({ default: autoAnimate }) => {
autoAnimate(parent);
});
}
}, [parent]);
문제: 아이템이 깜빡이며 애니메이션됨
해결 방법: 유니크 키 추가: key={item.id} (not key={index})
문제: 플렉스박스 폭 이슈
해결 방법: flex-grow: 1 대신 명시적인 폭 사용
문제: 테이블 행이 애니메이션되지 않음
해결 방법: 개별 <tr> 요소가 아닌 <tbody>에 ref 적용
전체 설정 체크리스트
-
@formkit/[email protected]설치 완료 - React 19+ (또는 Vue/Svelte) 사용 중
- 부모 요소에 ref 추가
- 부모 요소가 항상 렌더링됨 (조건부 아님)
- 리스트 아이템에 유니크하고 안정적인 키 사용
-
prefers-reduced-motion으로 테스트 완료 - Cloudflare Workers/Next.js 사용 시 SSR-안전
- 플렉스박스 폭 이슈 없음
- 개발 서버 오류 없이 실행
- 프로덕션 빌드 성공
질문이나 이슈가 있나요?
templates/에서 작동 예제 확인references/auto-animate-vs-motion.md에서 라이브러리 비교 확인references/ssr-patterns.md에서 SSR 우회 방법 확인- 공식 문서 확인: https://auto-animate.formkit.com
- GitHub 이슈 확인: https://github.com/formkit/auto-animate/issues
프로덕션 준비 완료? ✅ 예 - 13.6k 스타, 적극적으로 유지 관리, 의존성 제로.