React DOM 모션 · React Native Animated API

모션은 한 번만 쓰세요. 부드럽게 돌고, 끊기지 않습니다.

Animated는 React Native의 Animated를 웹으로 가져옵니다. 값 하나가 프레임마다 React 렌더 없이 원하는 만큼의 요소를 움직이고, 지원되는 모션은 브라우저가 직접 재생하며, 어디서 끊어도 화면에 보이는 위치에서 이어집니다.

시작하기 예제 보기

설치

npm install @kkwaenggwari/animated

시계 값 하나가 64개 도형의 물결을 모두 움직입니다. 무대 위로 포인터를 움직여 보세요.

이번 릴리스에서 측정한 값

1.0.0 빌드를 데스크톱 PC의 헤드리스 Chrome에서 측정했습니다. 수치는 기기에 따라 다릅니다. 측정 방법

0.00ms400개 요소가 움직이는 동안 프레임당 JavaScript
Animated 요소의 유한한 transform·opacity 모션은 브라우저가 재생합니다. 페이지의 프레임 콜백은 아무 일도 하지 않습니다.
0.13ms값 하나로 10,000개 요소를 움직일 때 프레임당 JavaScript
값은 CSS 변수 하나만 씁니다. 모든 요소는 CSS에서 그 변수로 자기 스타일을 계산합니다.
0모션 중 React 렌더
값은 React 상태를 거치지 않습니다. 컴포넌트는 프레임이 아니라 props가 바뀔 때만 렌더됩니다.

01 · 편함

이미 아는 API를, 평범한 React style에

timing, spring, interpolate, loop, Animated.event는 React Native의 이름과 설정을 그대로 씁니다. 값은 평범한 style prop에 바로 들어가므로 첫 모션 전에 따로 배울 컴포넌트가 없습니다.

React Native 코드는 Animated.View를 Animated.div로 바꾸면 옮겨집니다.
값 하나가 막대, 다이얼, 카드 줄을 각자의 범위로 동시에 움직입니다.
useAnimated가 레시피를 소유합니다. 마운트 때 시작하고, 의존성이 바뀌면 다시 시작하고, 언마운트 때 정리합니다.

예제를 준비하는 중…

JavaScript가 꺼져 있습니다. 아래 코드가 예제의 전체 소스입니다.

App.jsx

import { Easing, delay, loop, sequence, spring, timing, useAnimated } from '@kkwaenggwari/animated';
import './styles.css';

const curves = {
  linear: Easing.linear,
  inOut: Easing.inOut(Easing.cubic),
  back: Easing.out(Easing.back(1.7)),
  bounce: Easing.bounce,
};

export default function App({ tempo = 'spring', duration = 900, easing = 'inOut' }) {
  // One value. The recipe restarts when a prop changes.
  const progress = useAnimated(
    0,
    (value) => {
      const go = (toValue) =>
        tempo === 'spring'
          ? spring(value, { toValue, stiffness: 120, damping: 11 })
          : timing(value, { toValue, duration, easing: curves[easing] });
      loop(sequence([go(1), delay(500), go(0), delay(500)]));
    },
    [tempo, duration, easing],
  );

  const x = progress.interpolate({ inputRange: [0, 1], outputRange: ['0px', '200px'] });
  const turn = progress.interpolate({ inputRange: [0, 1], outputRange: ['-90deg', '180deg'] });

  return (
    <div className="stage">
      <div className="track">
        <div className="fill" style={{ transform: `scaleX(${progress})` }} />
      </div>
      <div className="row">
        <div className="dial">
          <i style={{ transform: `rotate(${turn})` }} />
        </div>
        <div className="lane">
          <div className="puck" style={{ transform: `translateX(${x})` }} />
        </div>
      </div>
      <div className="cards">
        {[0, 1, 2, 3].map((index) => {
          const start = index * 0.15;
          const lift = progress.interpolate({
            inputRange: [start, start + 0.55],
            outputRange: ['0px', '-26px'],
            extrapolate: 'clamp',
          });
          return (
            <div key={index} className="card" style={{ transform: `translateY(${lift})` }}>
              {index + 1}
            </div>
          );
        })}
      </div>
      <p className="note">One value → 7 elements, ordinary React style</p>
    </div>
  );
}

styles.css

.stage {
  display: grid;
  gap: 22px;
  padding: 28px;
}

.track {
  height: 12px;
  border-radius: 999px;
  background: #eef2ff;
  overflow: hidden;
}

.fill {
  height: 100%;
  background: #2854ff;
  transform-origin: left center;
}

.row {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 24px;
}

.dial {
  position: relative;
  flex: none;
  width: 72px;
  height: 72px;
  border: 2px solid #e4e6ef;
  border-radius: 50%;
}

.dial i {
  position: absolute;
  inset: 50% auto auto 50%;
  width: 30px;
  height: 4px;
  margin-top: -2px;
  border-radius: 2px;
  background: #8fb0ff;
  transform-origin: left center;
}

.lane {
  flex: 1 1 244px;
  max-width: 260px;
  height: 44px;
  border-radius: 999px;
  background: #f5f6fb;
}

.puck {
  width: 44px;
  height: 44px;
  border-radius: 50%;
  background: #5c7cff;
}

.cards {
  display: flex;
  gap: 12px;
  padding-top: 30px;
}

.card {
  display: grid;
  place-items: center;
  width: 64px;
  height: 64px;
  border-radius: 14px;
  background: #16181d;
  color: #fff;
  font-weight: 700;
}

.note {
  margin: 0;
  color: #5b6070;
  font-size: 14px;
}

React Native와 같은 호출

Spinner.jsx

// React Native
<Animated.View style={{ transform: [{ rotate }] }} />

// React DOM with @kkwaenggwari/animated — the rest is identical
<Animated.div style={{ transform: [{ rotate }] }} />

const spin = useAnimatedValue(0);
const rotate = spin.interpolate({ inputRange: [0, 1], outputRange: ['0deg', '360deg'] });

Animated.loop(
  Animated.timing(spin, { toValue: 1, duration: 900, easing: Easing.linear, useNativeDriver: true }),
).start();

02 · 빠름

프레임마다 React 렌더가 없습니다

훅 값은 CSS 변수입니다. 선형 보간과 사칙연산은 그 변수의 정확한 calc() 식이 되므로 프레임마다 한 번만 쓰고 나머지는 브라우저가 계산합니다. Animated.<tag> 요소의 유한한 transform·opacity 모션은 프레임 콜백 없이 브라우저가 재생합니다.

점 개수를 바꿔 보세요. React는 변경마다 한 번 렌더되고, 프레임마다 렌더되지 않습니다.
scope는 값을 요소마다가 아니라 컨테이너에 한 번만 씁니다.
inspect(element)는 속성마다 어떤 경로로 재생되는지와 그 이유를 알려 줍니다.

예제를 준비하는 중…

JavaScript가 꺼져 있습니다. 아래 코드가 예제의 전체 소스입니다.

App.jsx

import { useRef } from 'react';
import { Easing, loop, timing, useAnimated } from '@kkwaenggwari/animated';
import './styles.css';

export default function App({ count = 1600, amplitude = 16, duration = 2400 }) {
  const field = useRef(null);
  const renders = useRef(0);
  renders.current += 1;

  // Written once per frame on the field; every dot derives from it in CSS.
  const wave = useAnimated(
    0,
    (value) => {
      loop(timing(value, { toValue: 1, duration, easing: Easing.linear }));
    },
    [duration],
    { scope: field },
  );

  const columns = Math.ceil(Math.sqrt(count * 2.8));
  const dots = Array.from({ length: count }, (_, index) => index);

  return (
    <div className="stage">
      <div className="meta">
        <span>{count.toLocaleString('en-US')} dots</span>
        <span>React renders: {renders.current}</span>
      </div>
      <div className="field" ref={field} style={{ gridTemplateColumns: `repeat(${columns}, 1fr)` }}>
        {dots.map((index) => {
          const phase = (index % columns) / columns + Math.floor(index / columns) / 18;
          return (
            <i
              key={index}
              style={{
                transform: `translateY(calc(sin((${wave} + ${phase}) * 1turn) * ${amplitude}px))`,
                opacity: `calc(0.55 + cos((${wave} + ${phase}) * 1turn) * 0.45)`,
              }}
            />
          );
        })}
      </div>
    </div>
  );
}

styles.css

.stage {
  display: grid;
  gap: 16px;
  padding: 24px;
}

.meta {
  display: flex;
  flex-wrap: wrap;
  justify-content: space-between;
  gap: 8px;
  font:
    600 14px/1.4 ui-monospace,
    SFMono-Regular,
    Consolas,
    monospace;
  color: #1a33c7;
}

.field {
  display: grid;
  grid-auto-rows: 1fr;
  gap: 2px;
  height: 280px;
  padding: 28px 16px;
  border-radius: 16px;
  background: #0b1440;
  overflow: hidden;
}

.field i {
  display: block;
  width: 100%;
  max-width: 8px;
  aspect-ratio: 1;
  align-self: center;
  justify-self: center;
  border-radius: 50%;
  background: #5c7cff;
}

.field i:nth-child(3n) {
  background: #8fb0ff;
}

.field i:nth-child(7n) {
  background: #ffffff;
}

03 · 안정

어디서 끊어도 이어집니다

새 목표는 요소가 화면에 있는 위치에서 출발하고, 스프링은 속도까지 이어받습니다. 그래서 도중에 방향을 바꾸면 멈췄다 가는 대신 부드럽게 돕니다. 훅에서 선언한 컨트롤러는 교체와 언마운트 때 멈추고 해제되며, 서버에서 렌더한 마크업은 하이드레이션 뒤에도 계속 움직입니다.

빠르게 두 번 눌러 보세요. spring은 경로가 휘고, timing은 위치를 이어받되 새 곡선으로 출발합니다.
멈추면 값은 그 자리에 남습니다. 끝 상태로 튀지 않습니다.
언마운트, 경로 이동, 숨겨진 탭 뒤에 남는 프레임 루프가 없습니다.

예제를 준비하는 중…

JavaScript가 꺼져 있습니다. 아래 코드가 예제의 전체 소스입니다.

App.jsx

import { useRef } from 'react';
import {
  Easing,
  spring,
  timing,
  useAnimatedListener,
  useAnimatedValueXY,
} from '@kkwaenggwari/animated';
import './styles.css';

export default function App({ tempo = 'spring', stiffness = 140, damping = 14 }) {
  const point = useAnimatedValueXY({ x: 80, y: 120 });
  const canvas = useRef(null);

  const moveTo = (event) => {
    const box = event.currentTarget.getBoundingClientRect();
    const toValue = { x: event.clientX - box.left, y: event.clientY - box.top };
    // A new target starts from where the puck is now.
    const motion =
      tempo === 'spring'
        ? spring(point, { toValue, stiffness, damping })
        : timing(point, { toValue, duration: 700, easing: Easing.inOut(Easing.cubic) });
    motion.start();
  };

  // Draw the path the puck actually travels.
  const last = useRef(null);
  useAnimatedListener(point, ({ x, y }) => {
    const context = canvas.current?.getContext('2d');
    if (!context) return;
    context.fillStyle = 'rgba(11, 20, 64, 0.025)';
    context.fillRect(0, 0, context.canvas.width, context.canvas.height);
    if (last.current) {
      context.strokeStyle = tempo === 'spring' ? '#8fb0ff' : '#ffffff';
      context.lineWidth = 4;
      context.lineCap = 'round';
      context.beginPath();
      context.moveTo(last.current.x, last.current.y);
      context.lineTo(x, y);
      context.stroke();
    }
    last.current = { x, y };
  });

  return (
    <div className="stage">
      <div className="track" onPointerDown={moveTo}>
        <canvas ref={canvas} width={720} height={320} />
        <div
          className="puck"
          style={{
            transform: `translate(calc(${point.x} * 1px - 50%), calc(${point.y} * 1px - 50%))`,
          }}
        />
        <p>Click anywhere. Click again before it stops.</p>
      </div>
    </div>
  );
}

styles.css

.stage {
  padding: 20px;
}

.track {
  position: relative;
  height: 320px;
  border-radius: 16px;
  background: #0b1440;
  overflow: hidden;
  cursor: crosshair;
  touch-action: none;
  user-select: none;
}

.track canvas {
  position: absolute;
  inset: 0;
  width: 720px;
  height: 320px;
}

.puck {
  position: absolute;
  top: 0;
  left: 0;
  width: 36px;
  height: 36px;
  border: 3px solid #fff;
  border-radius: 50%;
  background: #2854ff;
}

.track p {
  position: absolute;
  inset: auto 16px 12px;
  margin: 0;
  color: #b8c4ef;
  font-size: 14px;
  pointer-events: none;
}

이런 것을 만들 수 있습니다

설정을 조절해 볼 수 있고 전체 소스를 가져갈 수 있는 완성 패턴입니다.

전체 예제

Animated 위에서 만든

완성된 컴포넌트가 필요하다면, Animated Chorus.

굴러가는 숫자, 옮겨 가는 탭 하이라이트, 진행 표시, 시트, 움직이는 목록을 React와 React Native에 바로 넣을 수 있습니다. 옆의 세 개가 지금 이 페이지에서 실제로 돌고 있습니다.

Animated Chorus 보기

3분이면 시작합니다

패키지를 설치하고 첫 값을 움직인 다음, 지금 하려는 일에 맞는 가이드를 고르세요.

npm install @kkwaenggwari/animated