ProgressBar

Property

---

Size

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

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

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 색으로 바뀝니다. 막대 색은 그대로입니다.

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으로 텍스트를 함께 두면 확대 화면이나 저시력 환경에서도 값을 읽을 수 있습니다.

Props Table

---

ProgressBar.Root

Loading component documentation...

ProgressBar.Label

Loading component documentation...

ProgressBar.Value

Loading component documentation...

ProgressBar.Track

Loading component documentation...

ProgressBar.Indicator

Loading component documentation...

ProgressBar.Description

Loading component documentation...