MotionNumber · MotionText

자리마다 바퀴처럼 구르는 숫자. 생기고 사라지는 자리까지.

웹React Native숫자와 글

직접 해 보기

예제를 준비하는 중…

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

App.jsx

import { useState } from 'react';
import { MotionNumber, MotionText, motionTokens } from '@kkwaenggwari/animated-chorus';
import './styles.css';

const formats = {
  plain: {},
  currency: { intl: true, locale: 'en-US', format: { style: 'currency', currency: 'USD' } },
  // Basis points: every preset and every ±1 step shows a different percentage.
  percent: { format: (value) => `${(value / 100).toFixed(2)}%` },
};

const presets = [9, 10, 999, 1000, 12480, 98765];

export default function App({
  mode = 'roll',
  direction = 'auto',
  format = 'currency',
  stagger = 40,
  spring = 'default',
}) {
  const [value, setValue] = useState(1000);
  const [trend, setTrend] = useState('Ready');

  const change = (next) => {
    setTrend(next > value ? 'Rising' : next < value ? 'Falling' : 'Same value');
    setValue(next);
  };

  return (
    <div className="lab">
      <MotionNumber
        className="value"
        value={value}
        mode={mode}
        direction={direction}
        stagger={stagger}
        transition={motionTokens.spring[spring]}
        {...formats[format]}
      />
      <MotionText className="trend">{trend}</MotionText>
      <div className="presets">
        {presets.map((preset) => (
          <button key={preset} onClick={() => change(preset)}>
            {preset}
          </button>
        ))}
      </div>
      <div className="steps">
        <button onClick={() => change(value - 1)}>−1</button>
        <button onClick={() => change(value + 1)}>+1</button>
        <button onClick={() => change(value * 10)}>×10</button>
        <button onClick={() => change(Math.round(value / 10))}>÷10</button>
      </div>
    </div>
  );
}

styles.css

.lab {
  display: grid;
  justify-items: center;
  gap: 14px;
  padding: 32px 20px 28px;
}

.value {
  font:
    800 clamp(44px, 11vw, 80px)/1.05 system-ui,
    sans-serif;
  font-variant-numeric: tabular-nums;
  letter-spacing: -0.03em;
  color: #0e2e24;
}

.trend {
  padding: 4px 12px;
  border-radius: 999px;
  background: #eaf6f0;
  color: #176b52;
  font-weight: 650;
  font-size: 14px;
}

.presets,
.steps {
  display: flex;
  flex-wrap: wrap;
  justify-content: center;
  gap: 8px;
}

.presets button,
.steps button {
  min-width: 56px;
  min-height: 44px;
  padding: 0 14px;
  border: 1px solid #cfe8dc;
  border-radius: 999px;
  background: #fff;
  font:
    600 15px system-ui,
    sans-serif;
  font-variant-numeric: tabular-nums;
  color: #0e2e24;
  cursor: pointer;
}

.steps button {
  background: #f4faf7;
}

.presets button:hover,
.steps button:hover {
  border-color: #176b52;
}

가장 짧은 사용법

Total.jsx

<MotionNumber value={count} />
<MotionNumber value={total} mode="roll" intl locale="en-US"
  format={{ style: 'currency', currency: 'USD' }} />
<MotionText>{status}</MotionText>

대신 처리하는 일

올림: 999 → 1,000에서 바뀌는 모든 자리가 주행 거리계처럼 같은 방향으로 구릅니다.
생기거나 사라지는 자리는 툭 나타나지 않고 자기 열에서 굴러 들어오고 나갑니다.
구분 기호, 부호, 통화 기호는 자기가 속한 자리와 함께 나타나고 사라집니다.
남는 자리는 구르면서 새 위치로 미끄러지므로 숫자가 갈라지지 않습니다.
움직이는 도중에 새 값이 오면 화면에 보이는 모습 그대로에서 이어갑니다.
Intl이 필요 없습니다. 글자나 format 함수를 넘기고, 원할 때만 intl을 켜세요.

이럴 때 쓰세요

상품을 담을 때마다 바뀌는 장바구니 합계.
실시간 카운터나 점수.
몇 초마다 새로 고치는 대시보드 수치.

Props

`MotionNumber`

Prop	타입	기본값	설명
`value`	`number \| bigint \| string`	`—`필수	숫자, 또는 호출자가 서식을 입힌 숫자 글자.
`mode`	`'replace' \| 'roll'`	`'replace'`	`replace`는 바뀐 자리를 한 칸 옮기고, `roll`은 사이의 숫자를 거쳐 갑니다.
`direction`	`'auto' \| 'digit' \| 'up' \| 'down'`	`'auto'`	`auto`는 크기 변화를 따라 올림이 한 방향으로 구르고, `digit`은 자리마다 따로 비교합니다.
`stagger`	`number`	`45`	일의 자리부터 바깥으로, 바뀐 자리 사이의 밀리초. 전체 물결 시간은 제한됩니다.
`format`	`(value) => string \| Intl.NumberFormatOptions`		보여 줄 글자를 돌려주는 함수, 또는 `Intl.NumberFormat` 옵션(`intl`과 함께).
`intl`	`boolean`	`false`	내장 `Intl.NumberFormat`을 씁니다. 기본으로 꺼져 있어 어떤 런타임도 `Intl`이 필요 없습니다.
`locale`	`string \| string[]`		`intl`에 쓸 로캘.
`prefix`	`string`		숫자 앞 글자.
`suffix`	`string`		숫자 뒤 글자.
`transition`	`Transition`	`spring`	시간 곡선 `{ duration, easing }` 또는 스프링 `{ tempo: 'spring', spring }`. 스프링은 끊겨도 속도를 이어갑니다.
`onMotionComplete`	`(value) => void`		자리가 모두 멈추면 값과 함께 실행됩니다.

`MotionText`

Prop	타입	기본값	설명
`children`	`ReactNode`		보여 줄 글자.
`as`	`element`	`'span'`	그릴 요소.
`transition`	`Transition`	`spring`	시간 곡선 `{ duration, easing }` 또는 스프링 `{ tempo: 'spring', spring }`. 스프링은 끊겨도 속도를 이어갑니다.
`onMotionComplete`	`(text) => void`		움직임이 멈추면 실행됩니다.

그 밖의 props는 그려지는 요소로 전달되므로 className, style, 이벤트 핸들러를 평소처럼 쓸 수 있습니다.

웹과 React Native

웹에서는 각 자리가 Web Animations API로 재생되는 작은 글자 묶음이며, 글자는 그대로 선택할 수 있습니다. MotionText는 어떤 글자든 움직입니다. 숫자 글자는 자리마다 구르고 다른 글자는 교체됩니다.

React Native에서는 숫자가 진짜 Text로 남아 레이아웃·선택·접근성이 그대로이며 줄바꿈과 numberOfLines도 동작합니다. 글자는 네이티브 드라이버로 움직입니다.