ProgressBox

진행 상태를 여러 개의 판이 차례로 채워지는 형태로 표시합니다. Neba 표면 위의 로딩 상태에 어울리는 형태입니다.

import { ProgressBox } from 'neba';

<ProgressBox />
<ProgressBox value={62} label="마이그레이션 중" showValue />

Props

Prop	타입	기본값	설명
value	number | null	null	min과 max 사이의 진행도. null(기본값)은 진행도를 아직 모르는 상태이며, 빈 막대가 아니라 미정 표시로 그려집니다
min	number	0	범위의 시작
max	number	100	범위의 끝
size공통	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	판 하나의 크기
color공통	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	의미론적 색 역할
label	ReactNode	—	무엇을 기다리는지. 값과 함께 스크린 리더가 읽습니다
showValue	boolean	false	도형 옆에 값을 글자로 보여 줍니다. format이 없으면 범위에 대한 백분율입니다
format	Intl.NumberFormatOptions	—	값을 어떻게 쓸지. 없으면 min…max에 대한 백분율, 설명되지 않은 범위에서 유일하게 성립하는 표기입니다
count	number	4	판의 개수. 넷이면 파도가 파도로 읽히면서도 한눈에 셀 수 있습니다. 기다리는 대상에 실제로 단계가 있다면 그 수를 넣으세요

<div>의 native 속성은 root로 전달됩니다. color와 children만 위 표와 이름이 겹쳐 제외됩니다.

value · min · max · format · showValue는 ProgressLinear와 동일하게 동작합니다. value가 null이면 판이 순서대로 밝아지는 indeterminate 상태입니다.

예시

count

판의 개수입니다. 값이 있을 때 판은 왼쪽부터 채워지고, 진행 중인 판은 부분적으로 채워집니다. 판 단위로만 채워지면 판 4개로는 0 · 25 · 50 · 75 · 100만 표현할 수 있기 때문입니다.

import { ProgressBox } from 'neba';

export default function ProgressBoxCounts() {
  return (
    <div className="flex flex-col gap-5">
      {[3, 4, 6, 10].map((count) => (
        <ProgressBox key={count} count={count} />
      ))}
    </div>
  );
}

단계 표시로 쓰기

count를 실제 단계 수에 맞추면 판 하나가 단계 하나가 됩니다. 진행 중인 단계의 판이 채워지는 중으로 표시됩니다.

import { useState } from 'react';
import { Button, ProgressBox } from 'neba';

const STEPS = ['Account', 'Workspace', 'Billing', 'Invite', 'Done'];

/**
 * When the thing being waited on genuinely has steps, `count` is the number of
 * them and the plates stop being a decoration.
 */
export default function ProgressBoxSteps() {
  const [step, setStep] = useState(2);

  return (
    <div className="flex flex-col items-start gap-4">
      <ProgressBox
        size="lg"
        count={STEPS.length}
        value={step}
        min={0}
        max={STEPS.length}
        color="success"
        label={STEPS[Math.min(step, STEPS.length - 1)]}
      />
      <div className="flex items-center gap-2">
        <Button
          size="sm"
          variant="outline"
          color="secondary"
          disabled={step === 0}
          onClick={() => setStep(step - 1)}
        >
          Back
        </Button>
        <Button size="sm" disabled={step === STEPS.length} onClick={() => setStep(step + 1)}>
          Next
        </Button>
      </div>
    </div>
  );
}

모션 줄이기

판은 위치가 움직이지 않고 채움과 빛 가장자리만 애니메이션합니다. prefers-reduced-motion에서는 주기가 느려집니다.

접근성

• role="progressbar"와 값 속성이 적용되고, label이 accessible name이 됩니다.
• indeterminate 상태는 0이 아니라 미정으로 보고됩니다.