ProgressLinear

진행률을 가로 막대로 표시합니다. 세 가지 progress 컴포넌트 중 가장 널리 쓰이는 형태입니다.

import { ProgressLinear } from 'neba';

<ProgressLinear value={64} label="에셋 업로드 중" showValue />
<ProgressLinear />

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에 대한 백분율, 설명되지 않은 범위에서 유일하게 성립하는 표기입니다
thickness	number	—	홈의 두께를 픽셀로 직접 정합니다. size는 옆에 붙는 글자 크기를 계속 맡습니다

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

value의 기본값은 null이며, 진행률을 알 수 없는 indeterminate 상태를 뜻합니다. 짧은 조각이 막대 위를 반복해 지나갑니다. 0을 주면 "아직 아무것도 진행되지 않음"이라는 다른 의미가 되므로 구분해서 쓰세요.

예시

size

import { ProgressLinear, type NebaSize } from 'neba';

const SIZES: NebaSize[] = ['xs', 'sm', 'md', 'lg', 'xl'];

export default function ProgressLinearSizes() {
  return (
    <div className="flex w-full max-w-96 flex-col gap-4">
      {SIZES.map((size) => (
        <ProgressLinear key={size} size={size} value={45} label={size} showValue />
      ))}
    </div>
  );
}

thickness

size는 라이브러리의 사다리 위 한 단계이고, thickness는 픽셀 값입니다. 페이지가 그 숫자 하나를 위해 존재할 때 쓰는 prop입니다. 바뀌는 것은 홈의 두께뿐이고, 옆에 붙는 라벨의 타입 스케일은 size가 계속 맡습니다.

<ProgressLinear value={62} thickness={12} />

min · max · format

표시되는 백분율은 100이 아니라 min…max 구간에 대한 비율입니다. showValue로 값을 옆에 띄우고, format에 Intl.NumberFormat 옵션을 주면 바이트나 파일 수, 금액처럼 숫자 자체를 보여 줄 수 있습니다.

import { useEffect, useState } from 'react';
import { ProgressLinear } from 'neba';

export default function ProgressLinearValues() {
  const [sent, setSent] = useState(0);

  useEffect(() => {
    const timer = setInterval(() => setSent((value) => (value >= 4000 ? 0 : value + 320)), 700);

    return () => clearInterval(timer);
  }, []);

  return (
    <div className="flex w-full max-w-96 flex-col gap-5">
      {/* A range that is not 0–100, shown as a percentage of itself. */}
      <ProgressLinear value={3} min={0} max={4} label="Step 3 of 4" showValue color="info" />

      {/* And the same range with the caller saying what the number means. */}
      <ProgressLinear
        value={sent}
        max={4000}
        label="Transferred"
        showValue
        format={{ style: 'unit', unit: 'megabyte' }}
      />
    </div>
  );
}

모션 줄이기

prefers-reduced-motion에서도 indeterminate 애니메이션이 멈추지는 않습니다. 대신 지나가던 조각이 사라지고 막대 전체가 색으로 맥동합니다.

접근성

• role="progressbar"와 값·범위 속성이 적용되고, indeterminate일 때는 aria-valuenow가 빠집니다.
• label이 accessible name이 되고, aria-valuetext는 화면에 표시된 값과 같은 내용을 전달합니다.