Animated Number

핵심 속성

TRAnimatedNumber는 애플리케이션 상태에서 받은 숫자를 표시해요. 타이머나 카운터 상태를 직접 관리하지 않아요. 기본 roll 애니메이션은 값의 증감 방향으로 바뀐 숫자를 이동하고, count는 숫자 값을 연속 보간한 뒤 같은 로케일 서식을 적용해요. 첫 렌더는 움직이지 않으므로 서버 렌더링과 hydration에서 최종 값이 바로 보여요.

설치

pnpm add @tinyrack/ui

@import '@tinyrack/ui/components/animated-number.css';

import { TRAnimatedNumber } from '@tinyrack/ui/components/animated-number';

플레이그라운드

사용법

예시

API

• value는 필수예요. 값이 바뀌면 선택한 애니메이션이 시작되며, 마운트할 때 0부터 움직이지 않아요.
• animation="roll"은 정수 자리를 오른쪽부터, 소수 자리를 왼쪽부터 맞춰요. rollDirection은 이 모드에만 적용돼요. animation="count"는 ease-out으로 보간한 숫자를 매 프레임 서식화해요.
• duration은 두 모드의 시간을 밀리초로 설정해요. 0과 음수는 즉시 최종 값을 표시하고, 유한하지 않은 값은 600으로 돌아가요.
• format과 locale은 Intl.NumberFormat에 전달해요. 두 설정 중 하나가 바뀌면 서로 다른 서식 사이를 움직이지 않고 현재 값을 즉시 새 서식으로 표시해요. NaN과 무한대도 애니메이션 없이 표시해요.
• 시각적인 숫자 레이어는 보조 기술에서 숨기고 서식화된 텍스트 하나만 남겨요. 값 변경을 기본으로 공지하지 않아요. 업데이트를 알려야 할 때만 네이티브 aria-live에 polite를 전달하세요.
• prefers-reduced-motion이 reduce이면 실행 중인 움직임을 취소하고 최종 값을 유지해요. 네이티브 span props, 이벤트 핸들러, 스타일, 클래스 이름, React 19 ref를 전달해요.