Progress

진행률을 시각적으로 표시하는 프로그레스 바 컴포넌트

개요

트랙(외부 바)과 인디케이터(내부 바)로 구성되어 0~100% 진행률을 표시합니다. 정적 표시와 점진 애니메이션을 모두 지원합니다.

주요 특징

• ✅ 정적/애니메이션: 값을 즉시 반영하거나 시작값→목표값으로 점진 증가
• ✅ imperative 제어: ref.goToPercentage(from, to, speed)로 애니메이션 실행
• ✅ 지연 동기화 라벨: 표시 퍼센트가 지연 갱신되며 100% 도달 시 즉시 반영
• ✅ 커스터마이징: 바 색상, 트랙 색상, 높이, 모서리 둥글기 설정
• ✅ 디자인 토큰: Foundation Progress 토큰 시스템 호환

기본 사용

percentage로 진행률을, showPercentage로 퍼센트 텍스트를 표시합니다.

<Progress percentage={40} showPercentage height={16} />

정적 퍼센트 표시

percentage를 지정하면 애니메이션 없이 즉시 진행률을 반영합니다.

<Progress percentage={25} showPercentage height={14} />
<Progress percentage={50} showPercentage height={14} />
<Progress percentage={100} showPercentage height={14} />

애니메이션 진행 (imperative)

ref.goToPercentage(from, to, speed)로 시작값에서 목표값까지 점진 애니메이션을 실행합니다.

const ref = useRef<ProgressRef>(null)
 
<Progress ref={ref} percentage={0} showPercentage height={16} />
<button onClick={() => ref.current?.goToPercentage(0, 100, 20)}>0 → 100</button>

애니메이션 진행 (animated)

animated가 true이면 percentage 변경 시 현재 값에서 목표값까지 애니메이션합니다.

<Progress percentage={pct} animated showPercentage height={16} />

커스텀 색상

barColor(인디케이터), trackColor(트랙 배경)로 색상을 지정합니다.

<Progress percentage={60} barColor="#16a34a" trackColor="#dcfce7" height={16} showPercentage />

모서리 둥글기 (radius)

radius로 모서리 둥글기를 조절합니다. 미지정 시 완전 둥근 형태입니다.

<Progress percentage={60} height={16} radius={0} />
<Progress percentage={60} height={16} radius={4} />
<Progress percentage={60} height={16} />

API Reference

Props

Ref

접근성

권장 사항

• ✅ role="progressbar"와 aria-value 속성이 자동 제공됨
• ✅ 진행 상태를 텍스트로도 전달 (showPercentage 또는 인접 레이블)
• ❌ 색상만으로 상태를 구분하지 않기

관련 컴포넌트

• Foundation Progress: 기본 Progress
• Steps: 단계별 진행 표시 컴포넌트