Progress

작업의 진행 상태를 시각적으로 표시하는 진행 바 컴포넌트

개요

Progress 컴포넌트는 base-ui의 Progress Primitive를 기반으로 구축된 진행 표시 컴포넌트입니다. 파일 업로드, 로딩, 폼 진행 등 작업의 완료 정도를 막대 형태로 표시하며, 라벨과 값 텍스트를 함께 구성할 수 있습니다.

주요 특징

• ✅ 컴파운드 컴포넌트: Track, Indicator, Label, Value 조합
• ✅ 값 범위 지정: min, max로 진행 범위 커스터마이징
• ✅ 불확정 상태: value={null}로 indeterminate 상태 표현
• ✅ 자동 Track 렌더링: children 없이 사용 시 Track/Indicator 자동 포함
• ✅ 접근성: role="progressbar", aria-valuenow 자동 적용
• ✅ 디자인 토큰: 테마 커스터마이징 지원

구조 (Anatomy)

<Progress value={50}>
  <ProgressLabel>라벨</ProgressLabel>
  <ProgressValue />
  {/* Track + Indicator는 자동 렌더링 */}
</Progress>

사용 예시

기본 사용

<Progress value={50} className="w-60" />

라벨과 값 표시

ProgressLabel과 ProgressValue로 진행 상태를 텍스트로 함께 표시합니다.

<Progress value={75} className="w-60">
  <ProgressLabel>로딩 중...</ProgressLabel>
  <ProgressValue />
</Progress>

다양한 진행 값

<Progress value={25} className="w-60">
  <ProgressLabel>업로드</ProgressLabel>
  <ProgressValue />
</Progress>
 
<Progress value={60} className="w-60">
  <ProgressLabel>다운로드</ProgressLabel>
  <ProgressValue />
</Progress>
 
<Progress value={100} className="w-60">
  <ProgressLabel>완료</ProgressLabel>
  <ProgressValue />
</Progress>

API Reference

Progress

진행 바의 루트 컴포넌트입니다. base-ui Progress.Root를 래핑하며, children 뒤에 Track + Indicator를 자동 렌더링합니다.

ProgressTrack

진행 바의 배경 트랙입니다. (Progress 내부에 자동 포함)

ProgressIndicator

현재 진행 값을 나타내는 인디케이터입니다. (Progress 내부에 자동 포함)

ProgressLabel

진행 상태의 라벨 텍스트입니다.

ProgressValue

현재 진행 값을 포맷된 텍스트로 표시합니다.

기본 사용법

import {
  Progress,
  ProgressLabel,
  ProgressValue,
} from "@vortex/ui-foundation"
 
// 기본 (Track/Indicator 자동 렌더링)
<Progress value={50} />
 
// 라벨 + 값 표시
<Progress value={75}>
  <ProgressLabel>로딩 중...</ProgressLabel>
  <ProgressValue />
</Progress>

접근성

ARIA 속성

• base-ui Progress 기반으로 role="progressbar" 자동 적용
• aria-valuenow, aria-valuemin, aria-valuemax가 현재 값에 맞게 자동 설정
• value={null}인 불확정 상태에서는 aria-valuenow가 생략되어 스크린 리더에 “진행 중”으로 전달

권장 사항

• ✅ ProgressLabel로 진행 중인 작업의 의미를 명확히 전달
• ✅ 진행률을 알 수 없는 작업에는 value={null} 사용
• ❌ 단순 로딩 스피너 용도로 사용하지 않기

관련 컴포넌트

• OverlayLoading: 전체 화면 로딩 오버레이
• Slider: 값 선택 슬라이더
• Badge: 상태 표시 배지