Element Animations

Apply animations to individual DOM elements

Transition Examples

How to use various transition effects:

import { transition } from '@ssgoi/react';
import { fade, scale, blur, slide, fly, rotate, bounce } from '@ssgoi/react/transitions';

// Fade transition
<div ref={transition({
  key: "fade-element",
  ...fade({ spring: { stiffness: 300, damping: 30 } })
})}>
  Fade effect
</div>

// Scale transition
<div ref={transition({
  key: "scale-element",
  ...scale({ spring: { stiffness: 300, damping: 30 } })
})}>
  Scale effect
</div>

// Blur transition
<div ref={transition({
  key: "blur-element",
  ...blur({ amount: 10, spring: { stiffness: 300, damping: 30 } })
})}>
  Blur effect
</div>

// Slide transition (with direction)
<div ref={transition({
  key: "slide-element",
  ...slide({ direction: 'left', spring: { stiffness: 300, damping: 30 } })
})}>
  Slide effect
</div>

// Fly transition (custom position)
<div ref={transition({
  key: "fly-element",
  ...fly({ x: 200, y: -50, spring: { stiffness: 300, damping: 30 } })
})}>
  Fly effect
</div>

// Rotate transition
<div ref={transition({
  key: "rotate-element",
  ...rotate({ spring: { stiffness: 300, damping: 30 } })
})}>
  Rotate effect
</div>

// Bounce transition
<div ref={transition({
  key: "bounce-element",
  ...bounce({ spring: { stiffness: 300, damping: 30 } })
})}>
  Bounce effect
</div>

Basic Structure

TransitionConfig Interface

interface TransitionConfig {
  spring?: {
    stiffness: number; // Spring stiffness (default: 300)
    damping: number; // Damping coefficient (default: 30)
  };
  tick?: (progress: number) => void; // in: 0→1, out: 1→0
  prepare?: (element: HTMLElement) => void; // Initial setup before animation starts
  onStart?: () => void;
  onEnd?: () => void;
}

Transition Definition

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

How it Works

1. On Mount: Execute in function when element is added to DOM
2. On Unmount: Execute out function before element is removed
3. Animation: Spring physics engine generates progress
   • in: 0 → 1
   • out: 1 → 0
4. tick Callback: Called every frame to update styles

Transition Presets

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

Framework-specific Usage

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 Behavior

key

• key must be unique within the page (to track animation state even when DOM is created/deleted)
• If key is not set, a default auto-key based on the call location is generated

in Animation

• progress: 0 → 1
• Executes when element appears
• Opacity from 0 to 1, from small size to original size

out Animation

• progress: 1 → 0
• Executes when element disappears
• Opacity from 1 to 0, from original size to small size

// Example: difference between in and 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 Callback

The stage where DOM elements are prepared before animation starts:

{
  in: {
    prepare: (element) => {
      // Set initial state before tick is executed
      element.style.willChange = 'opacity, transform';
    },
    tick: (progress) => ({
      opacity: progress,
      transform: `translateY(${20 * (1 - progress)}px)`
    })
  }
}