v0.10.0

ComponentsP3 본문

Progress

진행률 표시기 — role="progressbar" + aria-value 트리오. 결정(value 0–100)·불명(indeterminate) 두 모드, 모션은 transform만 사용합니다.

마지막 업데이트 2026-06-11

한눈에#

진행 정도를 막대로 보여주는 표시기입니다 — 끝을 아는 결정 모드(0–100)와 끝을 모르는 불명(indeterminate) 모드 두 가지로 동작합니다.

72%
진행 중
  • 결정·불명 2모드
  • role=progressbar
  • aria-value 트리오
  • transform만

결정 모드는 value만큼 채우고, 불명 모드는 바 일부가 왕복합니다

사용 시점#

진행률이나 진행 중 상태를 막대로 보여야 하면 Progress — 단순 대기나 골격 유지는 다른 컴포넌트입니다.

쓴다
60%

업로드·처리처럼 끝을 아는(결정) 또는 진행 중(불명) 상태를 막대로

대신 Spinner
Spinner

진행률 없이 잠깐 도는 인라인 단순 대기

대신 Skeleton
Skeleton

콘텐츠 레이아웃 골격을 유지해 CLS를 막아야 할 때

플레이그라운드#

컨트롤로 props를 조작하면 미리보기와 코드가 실시간 갱신됩니다.

import { Progress } from '@wds/ui-web';

<Progress />

변형#

72%
진행 중
결정 · 퍼센트 표시 · 불명(indeterminate)
  • 결정 모드 — value(0–100)만큼 바를 채웁니다. 범위 밖 값은 자동 클램프
  • indeterminate — 전체 소요를 모를 때. 바 일부가 왕복하고 value는 무시됩니다
  • showValue — 우측에 퍼센트(불명 모드에서는 '진행 중') 텍스트를 붙입니다

크기#

size prop이 없습니다 — 트랙 높이는 space.2(8px) 고정, 폭은 부모를 채웁니다.

상태#

  • 결정 모드의 바 폭 변화는 duration.normal 트랜지션으로 부드럽게 이어집니다
  • prefers-reduced-motion: reduce에서는 왕복 애니메이션이 정지합니다 — 진행 중이라는 사실은 showValue의 '진행 중' 라벨로 전달하세요

Props#

Prop타입기본값설명
valuenumber0진행률 0–100 — 범위 밖/NaN은 클램프. indeterminate면 무시
indeterminatebooleanfalse진행률 불명 모드 — 왕복 애니 + aria-valuenow 생략
showValuebooleanfalse퍼센트 텍스트 표시 (불명 모드에서는 '진행 중')
labelstring'진행률'progressbar의 aria-label
…restOmit<HTMLAttributes<div>, 'role'>—className 등 전달 (role 충돌은 타입에서 차단)

접근성#

  • role="progressbar" + aria-valuemin/max/now — 보조기술이 진행률을 읽습니다
  • indeterminate면 aria-valuenow를 생략 — "진행률 불명"이 표준 방식으로 전달됩니다
  • 기본 aria-label은 '진행률' — 문맥에 맞게 label로 바꾸세요 (예: '업로드 진행률')
  • 모션은 transform만 사용(컴포지터 친화), reduced-motion에서 정지

토큰#

component 토큰 없이 semantic을 직접 소비합니다(신설 기준 §4 미충족).

속성토큰
트랙color.surface-muted · 높이 space.2 · radius.full
바color.primary · radius.full
퍼센트 텍스트color.text-muted + font-size.caption + font-weight.medium
모션duration.normal + ease.standard (왕복 주기 1.4s — duration 토큰 범위 밖 리터럴, Skeleton 선례)