요소 애니메이션

개별 DOM 요소에 애니메이션 적용하기

Transition Playground

다양한 transition 효과를 직접 체험해보세요:

import { transition } from '@ssgoi/react';

// Using transition hook
<div
  ref={transition({
    key: "playground-element",
    in: (element) => ({
      spring: { stiffness: 300, damping: 30 },
      tick: (progress) => {
        element.style.opacity = progress.toString();
      }
    }),
    out: (element) => ({
      spring: { stiffness: 300, damping: 30 },
      tick: (progress) => {
        // Same as 'in' but progress goes from 1 to 0
      }
    })
  })}
>
  Your content here
</div>

기본 구조

TransitionConfig 인터페이스

interface TransitionConfig {
  spring?: {
    stiffness: number; // 스프링 강성 (기본: 300)
    damping: number; // 감쇠 계수 (기본: 30)
  };
  tick?: (progress: number) => void; // in: 0→1, out: 1→0
  prepare?: (element: HTMLElement) => void; // 애니메이션 시작 전 초기 설정
  onStart?: () => void;
  onEnd?: () => void;
}

트랜지션 정의

interface Transition {
  in?: (element: HTMLElement) => TransitionConfig;
  out?: (element: HTMLElement) => TransitionConfig;
}

동작 원리

1. 마운트 시: 요소가 DOM에 추가될 때 in 함수 실행
2. 언마운트 시: 요소가 제거되기 전 out 함수 실행
3. 애니메이션: 스프링 물리 엔진이 progress 생성
   • in: 0 → 1
   • out: 1 → 0
4. tick 콜백: 매 프레임마다 호출되어 스타일 업데이트

트랜지션 프리셋

import { fade, scale /** 등등 */ } from "@ssgoi/react/transitions";

프레임워크별 사용법

import { transition } from "@ssgoi/react";

<div
  ref={transition({
    key: "unique-key",
    in: (element) => ({
      tick: (progress) => {
        element.style.opacity = progress;
        element.style.transform = `translateY(${20 * (1 - progress)}px)`;
      },
    }),
    out: (element) => ({
      tick: (progress) => {
        element.style.opacity = 1 - progress;
      },
    }),
  })}
>
  Content
</div>

Progress 동작 방식

in 애니메이션

• progress: 0 → 1
• 요소가 나타날 때 실행
• 투명도 0에서 1로, 작은 크기에서 원래 크기로

out 애니메이션

• progress: 1 → 0
• 요소가 사라질 때 실행
• 투명도 1에서 0으로, 원래 크기에서 작은 크기로

// 예시: in과 out의 차이
{
  in: (element) => ({
    tick: (progress) => {
      // progress: 0 → 1
      element.style.opacity = progress;  // 0 → 1
    }
  }),
  out: (element) => ({
    tick: (progress) => {
      // progress: 1 → 0
      element.style.opacity = progress;  // 1 → 0
    }
  })
}

prepare 콜백

애니메이션이 시작되기 전에 DOM 요소를 준비하는 단계입니다:

{
  in: {
    prepare: (element) => {
      // tick이 실행되기 전에 초기 상태 설정
      element.style.willChange = 'opacity, transform';
    },
    tick: (progress) => ({
      opacity: progress,
      transform: `translateY(${20 * (1 - progress)}px)`
    })
  }
}

주의사항

• key는 페이지 내에서 고유해야 함 (돔이 생성되다가 삭제 혹은 삭제되다가 생성되어도 애니메이션 상태를 추적할 수 있도록)