Progress
먼저 보고, 그다음 계약을 읽습니다
측정 가능한 비동기 작업의 진척 바 — determinate / indeterminate.
Component intent의도와 경계 읽기
value 가 숫자면 0~max 사이 채움(translateX 로 indicator 이동), null 이면 indeterminate 로 좌→우 sweep 애니메이션(진척률 모름). variant 로 결과 색(success/danger)을 표현해 4-state 의 완료/실패도 같은 바로 시각화한다. Radix Progress 래퍼라 role/aria-value* 가 자동으로 붙는다. multi-step agent(예: 18섹션 IC 메모 7/18)·파일 업로드·배치 작업에 쓴다.
예제
SSOT에 등록된 실제 API 기준 snippet입니다. standalone 배지만 독립 실행 단위이며, fragment는 주변 state·handler 문맥을 생략합니다.
import { Progress } from "@axe/ui";<Progress value={7} max={18} aria-label="IC 메모 생성 진척" />import { Progress } from "@axe/ui";export function Example() { return ( <> {/* 진척률 모름 (sweep) */} <Progress value={null} aria-label="토큰 갱신 중" /> {/* 완료/실패 결과 색 */} <Progress value={100} variant="success" aria-label="완료" /> <Progress value={40} variant="danger" aria-label="중단됨" /> </> );}<div class="axe-progress" role="progressbar" aria-valuemin="0" aria-valuemax="100" aria-valuenow="60" aria-label="업로드 진척"> <div class="axe-progress__indicator" style="transform: translateX(-40%)"></div></div>Props
TSX 소스가 진실입니다. 주요 export 컴포넌트의 public API만 노출합니다.
| 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
value | number | null | — | null | 0 ~ max 진척값. null 이면 indeterminate(sweep). 범위를 벗어나면 0~max 로 clamp. |
max | number | — | 100 | 분모(진척의 100% 기준). |
variant | "default" | "success" | "danger" | — | "default" | indicator 색. default=--accent · success=--success · danger=--danger. |
...rest | Omit<React.ComponentPropsWithoutRef<typeof ProgressPrimitive.Root>, "value"> | — | — | className 병합, 나머지는 Radix Progress.Root(루트 div)로 전파 — 접근 이름을 위한 aria-label/aria-labelledby 등을 여기로 넘긴다. |
.axe-* 클래스 계약
React 밖에서도 같은 표면을 그리는 공개 계약입니다. stable은 minor 버전 안에서 이름을 바꾸지 않습니다.
| 클래스 | 안정성 | 용도 |
|---|---|---|
.axe-progress | stable | 트랙 루트 — 높이 6px·subtle 배경·pill radius·overflow hidden. |
.axe-progress__indicator | stable | 채움 바 — accent 배경, translateX 로 진척 표현(transition). |
.axe-progress--success | stable | success 변형 — indicator = --success. |
.axe-progress--danger | stable | danger 변형 — indicator = --danger. |
.axe-progress--indeterminate | stable | indeterminate 변형 — indicator 를 33% 폭 sweep 으로 전환. |
접근성
키보드, ARIA, 구현 노트를 함께 검토합니다.
Radix 가 role="progressbar" + aria-valuemin=0 · aria-valuemax=max · aria-valuenow(=value, indeterminate 면 생략) · aria-valuetext(기본 "N%", indeterminate 면 생략) · data-state(loading|complete|indeterminate)를 붙인다.
비대화 요소라 키보드 상호작용 없음. Radix 는 접근 이름을 자동 생성하지 않으므로 aria-label 또는 연결 라벨(aria-labelledby)을 반드시 준다. prefers-reduced-motion 시 indicator transition·sweep 정지(indeterminate 는 전체 폭 0.6 opacity 로 정적 표시).