Progress

작업 진행률을 시각적으로 표시하는 Next.js Client Component입니다. 선형·원형, 색상·크기 변형, 줄무늬·불확정 상태를 지원하며 role="progressbar" ·aria-valuenow로 접근성을 보장합니다.

기본

`progress` · `progress_track` · `progress_bar`로 트랙과 채움 막대를 구성합니다. `progress_bar`의 `style="width: …"` 또는 CSS 변수로 진행률을 제어합니다.

레이블 · 값

`progress_header`에 `progress_label` · `progress_value`를 함께 배치합니다.

파일 업로드42%

데이터 동기화67%

색상

공통 `color_*` 클래스로 의미를 표현합니다.

크기

`progress_sm` · `progress`(기본) · `progress_lg` 세 가지 높이를 지원합니다.

줄무늬 · 애니메이션

`progress_striped`로 줄무늬 패턴을, `progress_animated`와 함께 사용하면 흐르는 애니메이션을 적용합니다.

불확정

진행률을 알 수 없을 때 `is-indeterminate`를 사용합니다. `aria-valuenow`를 생략하거나 `aria-busy="true"`를 함께 지정합니다.

동기화 중…

바 안 텍스트

`progress_inside`로 막대 안에 퍼센트를 표시합니다. 막대가 좁을 때는 텍스트가 잘릴 수 있으니 충분한 너비를 확보합니다.

25%

80%

원형

`progress_circle`로 원형 진행률을 표시합니다. `style="--progress-percent: …"`로 채움 비율을 지정합니다.

25%

68%

50%

90%

너비

`progress_fit`은 최대 너비를 제한하고, `progress_block`은 부모 너비 전체를 사용합니다.

progress_fit50%

progress_block — 전체 너비72%

마크업

선형 Progress는 progress_track에role="progressbar"를 지정하고,progress_bar의style="width: ..."로 진행률을 제어합니다. 원형은--progress-percent CSS 변수를 사용합니다.

<!-- 선형 기본 -->
<div class="progress progress_fit color_primary">
  <div class="progress_header">
    <span class="progress_label">업로드 중</span>
    <span class="progress_value">60%</span>
  </div>
  <div class="progress_track" role="progressbar"
    aria-valuenow="60" aria-valuemin="0" aria-valuemax="100"
    aria-label="업로드 진행률">
    <span class="progress_bar" style="width: 60%"></span>
  </div>
</div>

<!-- 불확정 -->
<div class="progress progress_fit is-indeterminate color_primary">
  <div class="progress_track" role="progressbar"
    aria-valuemin="0" aria-valuemax="100" aria-label="처리 중" aria-busy="true">
    <span class="progress_bar"></span>
  </div>
</div>

<!-- 원형 -->
<div class="progress progress_circle color_primary" role="progressbar"
  aria-valuenow="75" aria-valuemin="0" aria-valuemax="100"
  aria-label="진행률" style="--progress-percent: 75">
  <svg class="progress_circle-svg" viewBox="0 0 100 100" aria-hidden="true">
    <circle class="progress_circle-track" cx="50" cy="50" r="45" />
    <circle class="progress_circle-bar" cx="50" cy="50" r="45" />
  </svg>
  <span class="progress_circle-value">75%</span>
</div>

API · Progress Props

Prop	타입	기본값	설명
`percent`	number	0	0–100 범위로 보정되는 진행률 (막대 width)
`status`	'success' \| 'exception'	—	완료·오류 색상
`color`	'primary' \| 'success' \| 'warning' \| 'danger'	primary	막대 색상 color_*
`size`	'sm' \| 'md' \| 'lg'	md	progress_sm · progress_lg
`label`	string	—	헤더 라벨
`showInfo`	boolean	false	퍼센트 값 표시
`striped`	boolean	false	줄무늬 (progress_striped)
`animated`	boolean	false	흐르는 애니메이션
`indeterminate`	boolean	false	불확정 (is-indeterminate)
`inside`	boolean	false	막대 안 퍼센트 텍스트
`block`	boolean	false	전체 너비 (progress_block)
`ariaLabel`	string	진행률	progressbar 라벨
`className`	string	—	progress 루트에 추가 클래스

API · ProgressCircle Props

Prop	타입	기본값	설명
`percent`	number	0	0–100 범위로 보정되는 진행률 (--progress-percent)
`color`	'primary' \| 'success' \| 'warning' \| 'danger'	primary	color_*
`size`	'sm' \| 'md' \| 'lg'	md	progress_sm · progress_lg
`ariaLabel`	string	진행률	progressbar 라벨
`className`	string	—	progress_circle 루트에 추가 클래스

API · Children

Children	설명
`children`	지원하지 않음. label과 showInfo로 표시 콘텐츠를 구성

클래스 · 속성

React 컴포넌트가 렌더하는 OOCSS 클래스입니다. HTML 마크업으로 직접 작성할 때 동일하게 조합합니다.

클래스	설명
`progress · progress_track · progress_bar`	선형 진행률
`progress_circle · progress_circle-svg · progress_circle-value`	원형 진행률
`progress_header · progress_label · progress_value`	헤더
`progress_sm · progress_lg · progress_fit · progress_block`	크기·너비
`progress_striped · progress_animated · progress_inside`	스타일
`is-indeterminate`	불확정 상태
`color_primary · color_success · color_warning · color_danger`	색상

진행률은 progress_bar의width 또는 JS로 업데이트합니다. 시각적 값과 aria-valuenow를 함께 맞춰 주세요.

디자인 토큰

토큰	기본값	설명
`--progress-height · --progress-height-sm · --progress-height-lg`	8px · 4px · 12px	선형 트랙 높이
`--progress-max-width`	var(--input-max-width)	progress_fit 최대 너비
`--progress-circle-size · --progress-circle-stroke`	7.5rem · 6	원형 크기·stroke