ProgressBar

파일 업로드

Property

Size

Track의 높이를 설정합니다. sm md lg

Label과 Value의 글자 크기는 size와 무관하게 고정입니다.

Type

작업의 상태를 나타냅니다. default error

error는 Description을 danger 색으로 바꾸고, Track을 흐리게 낮추면서 Indicator를 아예 그리지 않습니다. 실패한 작업에 채워진 막대가 남아 있으면 진행 중으로 읽히기 때문입니다. 실패했다는 사실 자체는 Description 문구가 말해야 합니다.

report.pdf 업로드

10MB 중 4.2MB를 전송했습니다.x

report.pdf 업로드

업로드에 실패했습니다. 파일이 10MB를 넘습니다.x

Value Text

ProgressBar.Value는 선언한 범위를 기준으로 값을 백분율로 환산해 보여줍니다. min과 max를 바꾸면 화면에 보이는 값과 보조기기가 읽는 값이 함께 따라옵니다.

getAriaValueText로 문구를 직접 만들면 그 문자열이 aria-valuetext와 화면 텍스트에 동시에 쓰입니다. 두 청중이 서로 다른 값을 듣거나 보는 일이 없습니다.

디스크 검사

파일 업로드

Indeterminate

value에 null을 넣으면 진행률을 알 수 없는 상태가 됩니다. 30% 폭의 세그먼트가 Track을 왕복하며, aria-valuenow는 쓰이지 않습니다.

prefers-reduced-motion: reduce에서는 세그먼트가 멈춰 선 채로 표시됩니다.

서버 응답 대기 중

Examples

Description

ProgressBar.Description은 진행 상황을 말로 풀어 씁니다. 남은 용량, 실패 사유, 다음에 할 일 같은 것입니다. aria-describedby는 자동으로 이어지므로 id를 직접 붙일 필요가 없습니다. 직접 붙이면 그 id가 쓰입니다.

ProgressBar.Root의 type을 error로 바꾸면 이 텍스트가 danger 색이 되고, 막대는 Indicator 없이 흐린 Track만 남습니다.

report.pdf 업로드

10MB 중 4.2MB를 전송했습니다.x

Accessibility

ProgressBar.Label을 넣거나 ProgressBar.Root에 aria-label 또는 aria-labelledby를 주세요. 이름이 없으면 보조기기가 숫자만 읽습니다. 개발 모드에서는 이름이 없을 때 콘솔 경고가 나옵니다.
실패 사유나 다음 행동 같은 설명은 ProgressBar.Description에 넣으세요. type="error"가 바꾸는 것은 겉모습뿐입니다 — 실패했다는 사실은 문구가 직접 말해야 합니다. 색과 흐려진 막대만으로 오류를 전달하면 스크린 리더 사용자도, 빨강과 회색을 구별하지 못하는 사용자도 실패를 알 수 없습니다.
값이 바뀌어도 보조기기는 아무 말도 하지 않습니다. 포커스를 받지 않는 위젯의 값 변화는 조용합니다. 완료나 실패를 알려야 한다면 ProgressBar 바깥에 라이브 리전을 직접 두세요. role="progressbar" 요소의 자식은 표현용으로 취급되어 그 안의 라이브 리전은 접근성 트리에서 빠집니다.
```
<ProgressBar.Root value={value}>{/* ... */}</ProgressBar.Root>
<span role="status">{done ? '업로드 완료' : null}</span>
```
메시지는 완료·실패 시점에 한 번만 넣으세요. 값이 바뀔 때마다 갱신되는 라이브 리전은 스크린 리더를 뒤덮습니다.
min이 max보다 크거나 같으면 개발 모드에서 경고를 남기고 0–100으로 되돌립니다.
진행 상황을 막대 길이만으로 전달하지 마세요. ProgressBar.Value나 ProgressBar.Description으로 텍스트를 함께 두면 확대 화면이나 저시력 환경에서도 값을 읽을 수 있습니다.
보이는 라벨과 aria-label을 같이 쓴다면 보이는 문구를 aria-label 안에 그대로 넣으세요. 음성 명령 사용자는 화면에 적힌 말을 부르는데, 접근 가능한 이름이 그 말과 다르면 대상을 잡지 못합니다.
색을 재정의하면 대비는 직접 책임져야 합니다. Label·Value·Description 텍스트는 배경 대비 4.5:1, Indicator는 Track 대비 3:1을 넘겨야 합니다. 진행 정도를 알려주는 것은 두 면의 경계뿐입니다.
indeterminate 막대가 5초를 넘겨 돌고 페이지의 다른 콘텐츠와 함께 움직인다면 멈추거나 숨기는 수단을 두세요. prefers-reduced-motion은 그 설정을 켠 사용자에게만 닿기 때문에 WCAG 2.2.2를 대신하지 못합니다. 정지 버튼은 ProgressBar.Indicator의 애니메이션을 끄는 식으로 만듭니다.
```
<ProgressBar.Track>
    <ProgressBar.Indicator style={paused ? { animation: 'none' } : undefined} />
</ProgressBar.Track>
<Button onClick={() => setPaused((prev) => !prev)}>{paused ? '재생' : '정지'}</Button>
```
막대를 넓게 보이려고 화면 방향을 가로로 고정하지 마세요. Track은 부모 너비를 따라가므로 세로 화면에서도 그대로 동작합니다.
"빨간 막대를 확인하세요"처럼 색·모양·위치만 가리키는 안내는 쓰지 마세요. 어떤 작업이 어떻게 됐는지를 말로 적어야 합니다.
Label이나 Value 문구가 페이지 언어와 다르면 그 요소에 lang을 붙이세요. 스크린 리더가 엉뚱한 발음으로 읽습니다.
진행 중에 3초를 넘는 소리를 함께 낸다면 소리를 끄는 수단을 따로 두세요. 스크린 리더 사용자는 그 소리에 음성이 묻힙니다.
백분율이 뜻을 갖지 않는 작업에는 getAriaValueText로 실제 단위를 쓰세요. 파일 12개 중 3개, 40MB 중 12MB, 5단계 중 2단계 같은 문구가 "25%"보다 정확합니다.

Property

Size

Type

Value Text

Indeterminate

Examples

Description

Accessibility

Props Table

ProgressBar.Root

ProgressBar.Label

ProgressBar.Value

ProgressBar.Track

ProgressBar.Indicator

ProgressBar.Description

On this page