Communitygithub.com

AutoAnimate

AutoAnimate (@formkit/auto-animate) — React용 제로 설정 애니메이션 라이브러리. 리스트 전환, 아코디언, 토스트 알림, SSR 오류, 복잡한 애니메이션 라이브러리 문제를 해결합니다.

AutoAnimate란 무엇인가요?

AutoAnimate는 @formkit/auto-animate를 기반으로 한 제로 설정 애니메이션 라이브러리로, React, Vue, Svelte 등 모든 프레임워크에서 드롭인 방식으로 사용할 수 있습니다. 단 3.28KB(gzip)의 초경량 번들을 제공하며, 별도의 설정 없이 부모 요소에 ref를 추가하기만 하면 리스트 아이템의 추가, 제거, 재정렬 시 자동으로 부드러운 애니메이션을 적용합니다. 특히 SSR(Next.js, Cloudflare Workers) 환경에서 발생하는 오류, 조건부 렌더링 문제, 유니크 키 누락, 플렉스박스 폭 이슈 등 자주 보고된 10개 이상의 알려진 문제를 사전에 차단하는 방법을 상세히 안내합니다. 사용자의 `prefers-reduced-motion` 설정을 자동으로 존중하여 접근성을 해치지 않으며, 복잡한 제스처나 키프레임 제어가 필요한 경우 Motion 라이브러리 사용을 권장하는 명확한 기준도 제공합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ComeOnOliver/skillshub/tree/HEAD/skills/secondsky/claude-skills/auto-animate

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

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를 절대 설정하지 마세요. 접근성을 해칩니다.


공식 문서


패키지 버전 (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)

문제 해결

문제: 애니메이션이 동작하지 않음

해결 방법: 다음 일반적인 문제를 확인하세요.

  1. 부모 요소가 항상 DOM에 있나요? (조건부 렌더링 금지)
  2. 아이템에 유니크하고 안정적인 키가 있나요?
  3. 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-안전
  • 플렉스박스 폭 이슈 없음
  • 개발 서버 오류 없이 실행
  • 프로덕션 빌드 성공

질문이나 이슈가 있나요?

  1. templates/에서 작동 예제 확인
  2. references/auto-animate-vs-motion.md에서 라이브러리 비교 확인
  3. references/ssr-patterns.md에서 SSR 우회 방법 확인
  4. 공식 문서 확인: https://auto-animate.formkit.com
  5. GitHub 이슈 확인: https://github.com/formkit/auto-animate/issues

프로덕션 준비 완료? ✅ 예 - 13.6k 스타, 적극적으로 유지 관리, 의존성 제로.

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ComeOnOliver/skillshub

Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Use when the user wants to build a presentation, convert a PPT/PPTX to web, or create slides for a talk/pitch. Helps non-designers discover their aesthetic through visual exploration rather than abstract choices.

ComeOnOliver/skillshub

Next.js 16+ 和 Turbopack — 增量打包、文件系统缓存、开发速度,以及何时使用 Turbopack 与 webpack。

ComeOnOliver/skillshub

SwiftUI architecture patterns, state management with @Observable, view composition, navigation, performance optimization, and modern iOS/macOS UI best practices.

ComeOnOliver/skillshub

See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- extract frames, build visual/semantic/temporal indexes, and search moments with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio, video), and create real time alerts for events from live streams or desktop capture.

ComeOnOliver/skillshub

AI-assisted video editing workflows for cutting, structuring, and augmenting real footage. Covers the full pipeline from raw capture through FFmpeg, Remotion, ElevenLabs, fal.ai, and final polish in Descript or CapCut. Use when the user wants to edit video, cut footage, create vlogs, or build video content.

ComeOnOliver/skillshub

Next.js 15 애플리케이션을 위한 프론트엔드 개발 가이드라인. React 19, TypeScript, Shadcn/ui, Tailwind CSS를 사용한 모던 패턴. Server Components, Client Components, App Router, 파일 구조, Shadcn/ui 컴포넌트, 성능 최적화, TypeScript 모범 사례 포함. 컴포넌트, 페이지, 기능 생성, 데이터 페칭, 스타일링, 라우팅, 프론트엔드 코드 작업 시 사용.

ComeOnOliver/skillshub

Provides Tamagui patterns for config v4, compiler optimization, styled context, and cross-platform styling. Must use when working with Tamagui projects (tamagui.config.ts, @tamagui imports).

ComeOnOliver/skillshub

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

ComeOnOliver/skillshub

Create high-converting, visually distinctive landing pages. Use when building marketing pages, product launches, SaaS homepages, or any single-page conversion-focused website. Guides section-by-section composition with anti-AI-slop principles.

ComeOnOliver/skillshub

Auto-loaded context for Portfolio Buddy 2 development. Use for ANY task involving: React 19 development, TypeScript, portfolio analysis features, metrics calculations, trading strategy comparison, or working with the Portfolio Buddy 2 codebase. Contains tech stack, known issues, and architectural constraints.

ComeOnOliver/skillshub

Next.js development tooling via MCP. Inspect routes, components, build info, and debug Next.js apps. Use when working on Next.js applications, debugging routing, or inspecting app structure. NOT for general React or non-Next.js projects.

ComeOnOliver/skillshub

Implement UI using Shadcn MCP (atoms/theme) and 21st.dev MCP (complex sections). Use when adding buttons, layouts, or generating landing pages.

ComeOnOliver/skillshub

A conceptual skill for building an API client in Next.js that handles JWT tokens

ComeOnOliver/skillshub

Best practices and patterns for Next.js App Router, Server Actions, and Routing in this project.

ComeOnOliver/skillshub

The Design System, Theme, and UX rules for the Physical AI Hub.

ComeOnOliver/skillshub

Comprehensive frontend development skill for building modern, performant web applications using ReactJS, NextJS, TypeScript, Tailwind CSS. Includes component scaffolding, performance optimization, bundle analysis, and UI best practices. Use when developing frontend features, optimizing performance, implementing UI/UX designs, managing state, or reviewing frontend code.

ComeOnOliver/skillshub

This document captures learnings from fixing keyboard navigation issues when floating components (Select, DropdownMenu, Popover) have CSS open/close animations.

ComeOnOliver/skillshub

Build Next.js 16 applications with correct patterns and distinctive design. Use when creating pages, layouts, dynamic routes, upgrading from Next.js 15, or implementing proxy.ts. Covers breaking changes (async params/searchParams, Turbopack, cacheComponents) and frontend aesthetics. NOT when building non-React or backend-only applications.

ComeOnOliver/skillshub

Comprehensive Framer Motion animation library for React. Covers motion components, variants, gestures, page transitions, and scroll animations. Use when adding animations to React/Next.js applications.

ComeOnOliver/skillshub

Build interfaces that resonate, not just render. This skill enforces bold, intentional

관련 스킬