ProgressCircular

진행률을 원형 고리로 표시합니다. 가로 막대를 놓을 자리가 없는 좁은 공간에 씁니다.

import { ProgressCircular } from 'neba';

<ProgressCircular value={72} showValue label="색인 중" />
<ProgressCircular />

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 상태에서는 고리가 회전합니다. min · max · format은 ProgressLinear와 동일하게 동작합니다.

예시

size

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

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

export default function ProgressCircularSizes() {
  return (
    <div className="flex flex-wrap items-center gap-5">
      {SIZES.map((size) => (
        <ProgressCircular key={size} size={size} value={60} showValue />
      ))}
    </div>
  );
}

thickness

size는 고리의 지름이고, thickness는 고리 선의 두께를 픽셀로 정합니다. 화면이 그 수치 하나를 위해 존재할 때 쓰는 prop입니다. 두께는 고리 안쪽으로 잡히며, 반지름의 절반을 넘으면 가운데 구멍이 사라지므로 거기서 멈춥니다.

<ProgressCircular value={62} size="xl" thickness={6} />

컨트롤 안에 넣기

고리는 각 단계에서 컨트롤 높이보다 한 단계 작습니다. md 고리는 32px 컨트롤 안의 20px입니다. 버튼이나 필드, 표의 행에 넣어도 행 높이가 늘어나지 않습니다.

import { Button, Chip, ProgressCircular, TextField } from 'neba';

/**
 * The ring lands just under the control height at every step, so it drops into
 * a row of controls without making the row taller than it was.
 */
export default function ProgressCircularInline() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <TextField size="sm" placeholder="Search" endIcon={<ProgressCircular size="xs" />} />
      <Chip
        size="sm"
        variant="text"
        color="info"
        startIcon={<ProgressCircular size="xs" color="info" />}
      >
        Building
      </Chip>
      <Button size="sm" variant="outline" startIcon={<ProgressCircular size="xs" />}>
        Syncing
      </Button>
    </div>
  );
}

showValue와 label

값은 고리 안이 아니라 옆에 놓입니다. xs에서는 고리 지름이 14px이라 안쪽에 숫자가 들어갈 자리가 없기 때문입니다. showValue와 label은 고리와 한 줄로 정렬됩니다.

접근성

• SVG 그림 자체는 aria-hidden이고, 값은 바깥 요소의 role="progressbar"를 통해 전달됩니다.
• label이 accessible name이 됩니다.