Progress Bar

설치

pnpm dlx shadcn@latest add https://rebar.conmarket-landing.workers.dev/r/steel/progress-bar.json

pnpm dlx shadcn@latest add https://rebar.conmarket-landing.workers.dev/r/steel/progress-bar.json

class-variance-authority 를 설치하고 아래 코드를 components/ui/progress-bar.tsx 에 복사해요.

components/ui/steel/progress-bar.tsx

/** * @title Progress Bar * @description 진행 중인 작업이 얼마나 완료됐는지 가로 막대로 보여줘요. */import * as React from 'react';import { cva } from 'class-variance-authority';import { cn } from '@/lib/utils';// Atlassian @atlaskit/progress-bar — components/progress-bar 스펙const MIN_VALUE = 0;const MAX_VALUE = 1;// 원본 keyframes (increasingBarAnimation / decreasingBarAnimation)const keyframes = `@keyframes steel-progress-bar-increase{0%{left:-5%;width:5%}to{left:130%;width:100%}}@keyframes steel-progress-bar-decrease{0%{left:-80%;width:80%}to{left:110%;width:10%}}`;const containerVariants = cva('relative h-1.5 w-full overflow-hidden rounded-ds-full', {  variants: {    appearance: {      default: 'bg-ds-background-neutral',      success: 'bg-ds-background-neutral',      inverse: 'bg-ds-background-inverse-subtle',    },  },  defaultVariants: { appearance: 'default' },});const barVariants = cva('absolute block h-1.5 rounded-ds-full', {  variants: {    appearance: {      default: 'bg-ds-background-neutral-bold',      success: 'bg-ds-background-success-bold',      inverse: 'bg-ds-surface',    },  },  defaultVariants: { appearance: 'default' },});export interface CustomProgressBarProps {  /** 진행 값. `0` 부터 `1` 사이 */  value?: number;  /** 완료율을 알 수 없을 때 반복 애니메이션을 보여줘요. */  isIndeterminate?: boolean;  /** 보조 기술에 전달할 현재 상태 설명 (예: "완료: 10개 중 3개") */  ariaLabel?: string;  testId?: string;  className?: string;}export interface ProgressBarProps extends CustomProgressBarProps {  appearance?: 'default' | 'success' | 'inverse';}function ProgressBar({  appearance = 'default',  ariaLabel,  isIndeterminate = false,  testId = 'progress-bar',  value = 0,  className,}: ProgressBarProps) {  const clamped = Math.max(MIN_VALUE, Math.min(Number(value) || 0, MAX_VALUE));  const valueParsed = isIndeterminate ? MIN_VALUE : clamped;  return (    <div      data-slot="progress-bar"      data-appearance={appearance}      role="progressbar"      aria-label={ariaLabel}      aria-valuemin={MIN_VALUE}      aria-valuenow={valueParsed}      aria-valuemax={MAX_VALUE}      data-testid={testId}      className={cn(containerVariants({ appearance }), className)}    >      {isIndeterminate ? (        <>          <style href="steel-progress-bar" precedence="default">            {keyframes}          </style>          <span            data-slot="progress-bar-indicator"            className={cn(barVariants({ appearance }), 'animate-[steel-progress-bar-increase_2s_infinite]')}          />          <span            data-slot="progress-bar-indicator"            className={cn(              barVariants({ appearance }),              'animate-[steel-progress-bar-decrease_2s_infinite] [animation-delay:0.5s]',            )}          />        </>      ) : (        <span          data-slot="progress-bar-indicator"          style={{ width: `${clamped * 100}%` }}          className={cn(barVariants({ appearance }), 'transition-[width] duration-200')}        />      )}    </div>  );}/** 100% 에 도달하면 success 색으로 바뀌는 진행 막대예요. */function SuccessProgressBar({ isIndeterminate = false, value = 0, ...props }: CustomProgressBarProps) {  return (    <ProgressBar      appearance={value < 1 || isIndeterminate ? 'default' : 'success'}      value={value}      isIndeterminate={isIndeterminate}      {...props}    />  );}/** 진한 배경 위에서 대비를 유지하는 진행 막대예요. */function TransparentProgressBar(props: CustomProgressBarProps) {  return <ProgressBar appearance="inverse" {...props} />;}export { ProgressBar, SuccessProgressBar, TransparentProgressBar };

Examples

Default

기본 진행 막대예요. value 는 0 부터 1 사이 값이고, 범위를 벗어나면 잘라서 표시해요.

Inverse

진한 배경 위에서는 appearance="inverse" 를 써서 대비를 유지해요. 같은 동작을 하는 TransparentProgressBar 도 내보내요.

스프린트 진행률 60%

Success

작업이 끝났음을 알릴 때는 appearance="success" 를 써요.

Indeterminate

완료율을 계산할 수 없을 때는 isIndeterminate 로 막대가 계속 흘러가게 해요. 두 개의 막대가 0.5초 간격으로 2초씩 반복돼요.

Success progress bar

SuccessProgressBar 는 value 가 1 에 도달하는 순간 자동으로 success 색으로 바뀌어요. 보이는 도움말 문구도 함께 갱신해 주세요.

첨부 파일 10개 중 3개 업로드됨

내보내기	용도
`ProgressBar`	기본. `appearance` 로 default·success·inverse 를 골라요.
`SuccessProgressBar`	완료되면 자동으로 success 로 바뀌어요.
`TransparentProgressBar`	진한 배경용. 항상 inverse 예요.

Usage guidelines

진행 막대는 저장·변경 사항 처리, 파일 업로드·다운로드, 앱 로딩처럼 오래 걸리거나 단계가 복잡한 시스템 작업에 써요. 완료된 양을 계산할 수 있을 때 가장 잘 맞아요.

진행 막대는 진행선(채워지는 부분)과 컨테이너(전체 길이)로 이뤄져요. 진행선은 일부 채움, 완료, 불확정 상태를 가져요.
대기 시간이 짧다면 진행 막대 대신 Spinner 를 써요.
가능하면 막대 아래에 지금 무슨 작업이 진행 중인지 보이는 도움말 문구를 둬요.
계속 진행하는 데 필요한 작업이 끝나면 성공 상태를 분명하게 보여줘요.

Do· 작업 상태 표시

로딩 표시나 시스템 작업의 진행 상태를 보여줄 때 써요.

Don't· 데이터 시각화

차트나 비율 지표처럼 데이터를 보여주는 용도로 쓰지 않아요. 이런 경우는 별도 컴포넌트를 만들어요.

문구

상태를 뭉뚱그리지 말고 숫자로 구체적으로 써요. "업로드 중" 보다 "파일 10개 중 5개 업로드됨" 이 좋아요.
도움말 문구에는 지금 처리 중인 하위 작업 이름을 적어요.

Accessibility

role="progressbar" 와 aria-valuemin·aria-valuemax(0~1)·aria-valuenow 가 자동으로 붙어요. 불확정 상태에서는 aria-valuenow 가 0 이에요.
ariaLabel 에 현재 상태를 구체적으로 적어요. (예: "완료: 이슈 10개 중 3개")
같은 내용을 화면에도 보이는 문구로 함께 보여주면 모든 사용자가 진행 상황을 알 수 있어요.
진행 막대는 포커스를 받지 않아요.

/** * @title Progress Bar * @description 진행 중인 작업이 얼마나 완료됐는지 가로 막대로 보여줘요. */ import * as React from 'react'; import { cva } from 'class-variance-authority'; import { cn } from '@/lib/utils'; // Atlassian @atlaskit/progress-bar — components/progress-bar 스펙 const MIN_VALUE = 0; const MAX_VALUE = 1; // 원본 keyframes (increasingBarAnimation / decreasingBarAnimation) const keyframes = ` @keyframes steel-progress-bar-increase{0%{left:-5%;width:5%}to{left:130%;width:100%}} @keyframes steel-progress-bar-decrease{0%{left:-80%;width:80%}to{left:110%;width:10%}} `; const containerVariants = cva('relative h-1.5 w-full overflow-hidden rounded-ds-full', { variants: { appearance: { default: 'bg-ds-background-neutral', success: 'bg-ds-background-neutral', inverse: 'bg-ds-background-inverse-subtle', }, }, defaultVariants: { appearance: 'default' }, }); const barVariants = cva('absolute block h-1.5 rounded-ds-full', { variants: { appearance: { default: 'bg-ds-background-neutral-bold', success: 'bg-ds-background-success-bold', inverse: 'bg-ds-surface', }, }, defaultVariants: { appearance: 'default' }, }); export interface CustomProgressBarProps { /** 진행 값. `0` 부터 `1` 사이 */ value?: number; /** 완료율을 알 수 없을 때 반복 애니메이션을 보여줘요. */ isIndeterminate?: boolean; /** 보조 기술에 전달할 현재 상태 설명 (예: "완료: 10개 중 3개") */ ariaLabel?: string; testId?: string; className?: string; } export interface ProgressBarProps extends CustomProgressBarProps { appearance?: 'default' | 'success' | 'inverse'; } function ProgressBar({ appearance = 'default', ariaLabel, isIndeterminate = false, testId = 'progress-bar', value = 0, className, }: ProgressBarProps) { const clamped = Math.max(MIN_VALUE, Math.min(Number(value) || 0, MAX_VALUE)); const valueParsed = isIndeterminate ? MIN_VALUE : clamped; return ( <div data-slot="progress-bar" data-appearance={appearance} role="progressbar" aria-label={ariaLabel} aria-valuemin={MIN_VALUE} aria-valuenow={valueParsed} aria-valuemax={MAX_VALUE} data-testid={testId} className={cn(containerVariants({ appearance }), className)} > {isIndeterminate ? ( <> <style href="steel-progress-bar" precedence="default"> {keyframes} </style> <span data-slot="progress-bar-indicator" className={cn(barVariants({ appearance }), 'animate-[steel-progress-bar-increase_2s_infinite]')} /> <span data-slot="progress-bar-indicator" className={cn( barVariants({ appearance }), 'animate-[steel-progress-bar-decrease_2s_infinite] [animation-delay:0.5s]', )} /> </> ) : ( <span data-slot="progress-bar-indicator" style={{ width: `${clamped * 100}%` }} className={cn(barVariants({ appearance }), 'transition-[width] duration-200')} /> )} </div> ); } /** 100% 에 도달하면 success 색으로 바뀌는 진행 막대예요. */ function SuccessProgressBar({ isIndeterminate = false, value = 0, ...props }: CustomProgressBarProps) { return ( <ProgressBar appearance={value < 1 || isIndeterminate ? 'default' : 'success'} value={value} isIndeterminate={isIndeterminate} {...props} /> ); } /** 진한 배경 위에서 대비를 유지하는 진행 막대예요. */ function TransparentProgressBar(props: CustomProgressBarProps) { return <ProgressBar appearance="inverse" {...props} />; } export { ProgressBar, SuccessProgressBar, TransparentProgressBar };

/** * @title Progress Bar * @description 진행 중인 작업이 얼마나 완료됐는지 가로 막대로 보여줘요. */import * as React from 'react';import { cva } from 'class-variance-authority';import { cn } from '@/lib/utils';// Atlassian @atlaskit/progress-bar — components/progress-bar 스펙const MIN_VALUE = 0;const MAX_VALUE = 1;// 원본 keyframes (increasingBarAnimation / decreasingBarAnimation)const keyframes = `@keyframes steel-progress-bar-increase{0%{left:-5%;width:5%}to{left:130%;width:100%}}@keyframes steel-progress-bar-decrease{0%{left:-80%;width:80%}to{left:110%;width:10%}}`;const containerVariants = cva('relative h-1.5 w-full overflow-hidden rounded-ds-full', { variants: { appearance: { default: 'bg-ds-background-neutral', success: 'bg-ds-background-neutral', inverse: 'bg-ds-background-inverse-subtle', }, }, defaultVariants: { appearance: 'default' },});const barVariants = cva('absolute block h-1.5 rounded-ds-full', { variants: { appearance: { default: 'bg-ds-background-neutral-bold', success: 'bg-ds-background-success-bold', inverse: 'bg-ds-surface', }, }, defaultVariants: { appearance: 'default' },});export interface CustomProgressBarProps { /** 진행 값. `0` 부터 `1` 사이 */ value?: number; /** 완료율을 알 수 없을 때 반복 애니메이션을 보여줘요. */ isIndeterminate?: boolean; /** 보조 기술에 전달할 현재 상태 설명 (예: "완료: 10개 중 3개") */ ariaLabel?: string; testId?: string; className?: string;}export interface ProgressBarProps extends CustomProgressBarProps { appearance?: 'default' | 'success' | 'inverse';}function ProgressBar({ appearance = 'default', ariaLabel, isIndeterminate = false, testId = 'progress-bar', value = 0, className,}: ProgressBarProps) { const clamped = Math.max(MIN_VALUE, Math.min(Number(value) || 0, MAX_VALUE)); const valueParsed = isIndeterminate ? MIN_VALUE : clamped; return ( <div data-slot="progress-bar" data-appearance={appearance} role="progressbar" aria-label={ariaLabel} aria-valuemin={MIN_VALUE} aria-valuenow={valueParsed} aria-valuemax={MAX_VALUE} data-testid={testId} className={cn(containerVariants({ appearance }), className)} > {isIndeterminate ? ( <> <style href="steel-progress-bar" precedence="default"> {keyframes} </style> <span data-slot="progress-bar-indicator" className={cn(barVariants({ appearance }), 'animate-[steel-progress-bar-increase_2s_infinite]')} /> <span data-slot="progress-bar-indicator" className={cn( barVariants({ appearance }), 'animate-[steel-progress-bar-decrease_2s_infinite] [animation-delay:0.5s]', )} /> </> ) : ( <span data-slot="progress-bar-indicator" style={{ width: `${clamped * 100}%` }} className={cn(barVariants({ appearance }), 'transition-[width] duration-200')} /> )} </div> );}/** 100% 에 도달하면 success 색으로 바뀌는 진행 막대예요. */function SuccessProgressBar({ isIndeterminate = false, value = 0, ...props }: CustomProgressBarProps) { return ( <ProgressBar appearance={value < 1 || isIndeterminate ? 'default' : 'success'} value={value} isIndeterminate={isIndeterminate} {...props} /> );}/** 진한 배경 위에서 대비를 유지하는 진행 막대예요. */function TransparentProgressBar(props: CustomProgressBarProps) { return <ProgressBar appearance="inverse" {...props} />;}export { ProgressBar, SuccessProgressBar, TransparentProgressBar };

Progress Bar

설치Copy Anchor Link

수동 설치

ExamplesCopy Anchor Link

DefaultCopy Anchor Link

InverseCopy Anchor Link

SuccessCopy Anchor Link

IndeterminateCopy Anchor Link

Success progress barCopy Anchor Link

Usage guidelinesCopy Anchor Link

문구Copy Anchor Link

AccessibilityCopy Anchor Link

PropsCopy Anchor Link

On this page

설치