AnimatedNumber
대시보드·차트 KPI 숫자를 Intl.NumberFormat으로 포맷하고, from 값이 있을 때만 ease-out count-up을 실행하는 숫자 표시 컴포넌트입니다.
마지막 업데이트 2026-06-28
한눈에#
KPI 카드, 차트 헤더, 요약 표처럼 숫자가 바뀌는 곳에 쓰는 count-up 숫자 표시입니다. Intl.NumberFormat을 그대로 받아 locale·통화·퍼센트·단위 포맷을 맞추고, from을 준 경우에만 현재 값에서 최종 값까지 ease-out cubic 보간으로 애니메이션합니다. from을 생략하면 첫 렌더는 최종 value를 바로 보여 줍니다.
- Intl.NumberFormat
- ease-out count-up
- stable SR text
- reduced-motion fallback
대시보드 KPI — 시각 숫자는 빠르게 출발해 부드럽게 안착하고, 스크린리더 텍스트는 최종 값으로 고정
사용 시점#
권장 — 이렇게 쓰세요
지양 — 이러지 마세요
쓴다 — 카드·차트·테이블의 최종 수치가 바뀌었음을 부드럽게 보여줄 때
대신 Progress — 진행 상태 자체를 표현해야 할 때
대신 Sparkline — 숫자 변화의 방향·형태를 함께 보여줘야 할 때
포맷#
value와 from은 숫자만 받습니다. NaN이나 Infinity처럼 유한하지 않은 값은 안전하게 빈 텍스트로 표시해 대시보드 전체 렌더가 깨지지 않게 합니다.
애니메이션#
duration은 fast·normal·slow 또는 millisecond 숫자를 받습니다. 시각 보간은 easeOutCubic으로 빠르게 출발한 뒤 최종 값에 부드럽게 안착합니다. from을 생략하면 첫 렌더에서 0부터 올라가는 surprise 없이 최종 값이 바로 표시됩니다.
루트 span은 변화 방향을 data-wds-animated-number-direction="up|down|none"으로 노출합니다. 이 metadata는 방향별 계측이나 향후 digit-roll settle hint에 사용할 수 있으며, 값이 같거나 from이 없으면 none입니다.
Props#
| Prop | 타입 | 기본값 | 설명 |
|---|---|---|---|
value | number | — | Final numeric value to show and expose to assistive technology. |
from | number | — | Optional animation start value. Omitted from renders value immediately. |
locale | string | string[] | — | Locale passed to Intl.NumberFormat. |
formatOptions | NumberFormatOptions | — | Formatting options passed to Intl.NumberFormat. |
duration | AnimatedNumberDuration | normal | Animation duration preset or milliseconds. |
reducedMotion | boolean | false | Force reduced-motion rendering for this instance. OS reduced motion always wins. |
ariaLabel | string | — | Stable screen-reader text override. Defaults to the final formatted value. |
ref | Ref<HTMLSpanElement> | — | Native <span> ref (React 19 ref-as-prop). |
접근성#
- 시각 숫자는
aria-hidden="true"로 숨기고, 스크린리더 전용 텍스트는 최종 포맷 값으로 고정합니다 - 애니메이션 중간 프레임 값은 보조기술에 노출하지 않습니다
- OS
prefers-reduced-motion: reduce또는reducedMotionprop이 켜지면 RAF 애니메이션 없이 최종 값을 바로 렌더합니다 ariaLabel은 최종 값 대신 읽을 안정 텍스트가 필요할 때만 사용합니다
토큰#
component 토큰 없이 타입 숫자 기능과 motion 정책만 사용합니다.
| 속성 | 값 |
|---|---|
| 숫자 폭 | font-variant-numeric: tabular-nums |
| duration fast/normal/slow | 450ms / 700ms / 1100ms |
| reduced motion | 최종 값 즉시 표시 |