진행률

진행률 (Progress)

오래 걸리는 작업의 현재 진행 상태를 보여 주는 컴포넌트예요. 완료 비율과 상태를 시각적으로 표시해요.

출처: 문서

본문

언제 사용하나요 (When To Use)

작업을 완료하는 데 오랜 시간이 걸릴 때 Progress로 현재 진행률과 상태를 보여 줄 수 있어요.
작업이 현재 인터페이스를 방해하거나 백그라운드에서 2초 이상 실행되어야 할 때 사용해요.
작업의 완료 비율을 표시해야 할 때 사용해요.

예시 (Examples)

진행률 바 (Progress bar)

표준 진행률 바예요.

import React from 'react';
import { Flex, Progress } from 'antd';

const App: React.FC = () => (
  <Flex gap="small" vertical>
    <Progress percent={30} />
    <Progress percent={50} status="active" />
    <Progress percent={70} status="exception" />
    <Progress percent={100} />
    <Progress percent={50} showInfo={false} />
  </Flex>
);

export default App;

원형 진행률 바 (Circular progress bar)

원형 진행률 바예요.

import React from 'react';
import { Flex, Progress } from 'antd';

const App: React.FC = () => (
  <Flex gap="small" wrap>
    <Progress type="circle" percent={75} />
    <Progress type="circle" percent={70} status="exception" />
    <Progress type="circle" percent={100} />
  </Flex>
);

export default App;

미니 크기 진행률 바 (Mini size progress bar)

좁은 영역에 적합해요.

import React from 'react';
import { Flex, Progress } from 'antd';

const App: React.FC = () => (
  <Flex vertical gap="small" style={{ width: 180 }}>
    <Progress percent={30} size="small" />
    <Progress percent={50} size="small" status="active" />
    <Progress percent={70} size="small" status="exception" />
    <Progress percent={100} size="small" />
  </Flex>
);

export default App;

반응형 원형 진행률 바 (Responsive circular progress bar)

반응형 원형 진행률 바예요. width가 20보다 작으면 진행 정보가 Tooltip에 표시돼요.

import React from 'react';
import { Flex, Progress } from 'antd';

const App: React.FC = () => (
  <Flex align="center" gap="small">
    <Progress
      type="circle"
      railColor="#e6f4ff"
      percent={60}
      strokeWidth={20}
      size={14}
      format={(number) => `In progress, ${number}% complete`}
    />
    <span>Code release</span>
  </Flex>
);

export default App;

미니 크기 원형 진행률 바 (Mini size circular progress bar)

더 작은 원형 진행률 바예요.

import React from 'react';
import { Flex, Progress } from 'antd';

const App: React.FC = () => (
  <Flex wrap gap="small">
    <Progress type="circle" percent={30} size={80} />
    <Progress type="circle" percent={70} size={80} status="exception" />
    <Progress type="circle" percent={100} size={80} />
  </Flex>
);

export default App;

동적 (Dynamic)

동적 진행률 바가 더 좋아요.

import React, { useState } from 'react';
import { MinusOutlined, PlusOutlined } from '@ant-design/icons';
import { Button, Flex, Progress, Space } from 'antd';

const App: React.FC = () => {
  const [percent, setPercent] = useState<number>(0);

  const increase = () => {
    setPercent((prevPercent) => {
      const newPercent = prevPercent + 10;
      if (newPercent > 100) {
        return 100;
      }
      return newPercent;
    });
  };

  const decline = () => {
    setPercent((prevPercent) => {
      const newPercent = prevPercent - 10;
      if (newPercent < 0) {
        return 0;
      }
      return newPercent;
    });
  };

  return (
    <Flex vertical gap="small">
      <Flex vertical gap="small">
        <Progress percent={percent} type="line" />
        <Progress percent={percent} type="circle" />
      </Flex>
      <Space.Compact>
        <Button onClick={decline} icon={<MinusOutlined />} />
        <Button onClick={increase} icon={<PlusOutlined />} />
      </Space.Compact>
    </Flex>
  );
};

export default App;

커스텀 텍스트 형식 (Custom text format)

format prop으로 커스텀 텍스트를 설정할 수 있어요.

import React from 'react';
import { Flex, Progress } from 'antd';

const App: React.FC = () => (
  <Flex gap="small" wrap>
    <Progress type="circle" percent={75} format={(percent) => `${percent} Days`} />
    <Progress type="circle" percent={100} format={() => 'Done'} />
  </Flex>
);

export default App;

대시보드 (Dashboard)

type=dashboard로 설정하면 대시보드 스타일의 진행률을 쉽게 얻을 수 있어요.

import React, { useState } from 'react';
import { Flex, Progress, Segmented } from 'antd';
import type { ProgressProps } from 'antd';

type GapPlacement = NonNullable<ProgressProps['gapPlacement']>;

const App: React.FC = () => {
  const [gapPlacement, setGapPlacement] = useState<GapPlacement>('bottom');
  const [gapDegree, setGapDegree] = useState<number>(50);
  return (
    <Flex vertical gap="large">
      <div>
        gapDegree:
        <Segmented
          options={[
            { label: 50, value: 50 },

            { label: 100, value: 100 },
          ]}
          defaultValue={50}
          onChange={(value: number) => {
            setGapDegree(value);
          }}
        />
      </div>
      <div>
        gapPlacement:
        <Segmented
          options={[
            { label: 'start', value: 'start' },
            { label: 'end', value: 'end' },
            { label: 'top', value: 'top' },
            { label: 'bottom', value: 'bottom' },
          ]}
          defaultValue="bottom"
          onChange={(value: GapPlacement) => {
            setGapPlacement(value);
          }}
        />
      </div>
      <Progress type="dashboard" gapDegree={gapDegree} percent={30} gapPlacement={gapPlacement} />
    </Flex>
  );
};

export default App;

성공 구간이 있는 진행률 바 (Progress bar with success segment)

서로 다른 상태의 여러 진행 부분을 보여 줘요.

import React from 'react';
import { Flex, Progress, Tooltip } from 'antd';

const App: React.FC = () => (
  <Flex gap="small" vertical>
    <Tooltip title="3 done / 3 in progress / 4 to do">
      <Progress percent={60} success={{ percent: 30 }} />
    </Tooltip>
    <Flex gap="small" wrap>
      <Tooltip title="3 done / 3 in progress / 4 to do">
        <Progress percent={60} success={{ percent: 30 }} type="circle" />
      </Tooltip>
      <Tooltip title="3 done / 3 in progress / 4 to do">
        <Progress percent={60} success={{ percent: 30 }} type="dashboard" />
      </Tooltip>
    </Flex>
  </Flex>
);

export default App;

선 끝 모양 (Stroke Linecap)

strokeLinecap="butt"로 선 끝 모양을 round에서 butt로 바꿀 수 있어요. 자세한 내용은 stroke-linecap 참고.

import React from 'react';
import { Flex, Progress } from 'antd';

const App: React.FC = () => (
  <Flex vertical gap="small">
    <Progress strokeLinecap="butt" percent={75} />
    <Flex wrap gap="small">
      <Progress strokeLinecap="butt" type="circle" percent={75} />
      <Progress strokeLinecap="butt" type="dashboard" percent={75} />
    </Flex>
  </Flex>
);

export default App;

커스텀 선 그라데이션 (Custom line gradient)

그라데이션을 캡슐화했어요. circle과 dashboard는 그라데이션을 설정하면 strokeLinecap을 무시해요.

import React from 'react';
import { Flex, Progress } from 'antd';
import type { ProgressProps } from 'antd';

const twoColors: ProgressProps['strokeColor'] = {
  '0%': '#108ee9',
  '100%': '#87d068',
};

const conicColors: ProgressProps['strokeColor'] = {
  '0%': '#87d068',
  '50%': '#ffe58f',
  '100%': '#ffccc7',
};

const App: React.FC = () => (
  <Flex vertical gap="medium">
    <Progress percent={99.9} strokeColor={twoColors} />
    <Progress percent={50} status="active" strokeColor={{ from: '#108ee9', to: '#87d068' }} />
    <Flex gap="small" wrap>
      <Progress type="circle" percent={90} strokeColor={twoColors} />
      <Progress type="circle" percent={100} strokeColor={twoColors} />
      <Progress type="circle" percent={93} strokeColor={conicColors} />
    </Flex>
    <Flex gap="small" wrap>
      <Progress type="dashboard" percent={90} strokeColor={twoColors} />
      <Progress type="dashboard" percent={100} strokeColor={twoColors} />
      <Progress type="dashboard" percent={93} strokeColor={conicColors} />
    </Flex>
  </Flex>
);

export default App;

단계가 있는 진행률 바 (Progress bar with steps)

단계가 있는 진행률 바예요.

import React from 'react';
import { green, red } from '@ant-design/colors';
import { Flex, Progress } from 'antd';

const App: React.FC = () => (
  <Flex gap="small" vertical>
    <Progress percent={50} steps={3} />
    <Progress percent={30} steps={5} />
    <Progress percent={100} steps={5} size="small" strokeColor={green[6]} />
    <Progress percent={60} steps={5} strokeColor={[green[6], green[6], red[5]]} />
  </Flex>
);

export default App;

단계가 있는 원형 진행률 바 (Circular progress bar with steps)

단계와 색 구간을 지원하는 원형 진행률 바예요. 기본 gap은 2px이에요.

import React from 'react';
import { Flex, Progress, Slider, Typography } from 'antd';

const App: React.FC = () => {
  const [stepsCount, setStepsCount] = React.useState<number>(5);
  const [stepsGap, setStepsGap] = React.useState<number>(7);
  return (
    <>
      <Typography.Title level={5}>Custom count:</Typography.Title>
      <Slider min={2} max={10} value={stepsCount} onChange={setStepsCount} />
      <Typography.Title level={5}>Custom gap:</Typography.Title>
      <Slider step={4} min={0} max={40} value={stepsGap} onChange={setStepsGap} />
      <Flex wrap gap="medium" style={{ marginTop: 16 }}>
        <Progress
          type="dashboard"
          steps={8}
          percent={50}
          railColor="rgba(0, 0, 0, 0.06)"
          strokeWidth={20}
        />
        <Progress
          type="circle"
          percent={100}
          steps={{ count: stepsCount, gap: stepsGap }}
          railColor="rgba(0, 0, 0, 0.06)"
          strokeWidth={20}
        />
      </Flex>
    </>
  );
};

export default App;

진행률 크기 (Progress size)

진행률의 크기예요.

import React from 'react';
import { Flex, Progress } from 'antd';

const App: React.FC = () => (
  <Flex vertical gap="medium">
    <Flex vertical gap="small" style={{ width: 300 }}>
      <Progress percent={50} />
      <Progress percent={50} size="small" />
      <Progress percent={50} size={[300, 20]} />
    </Flex>
    <Flex align="center" wrap gap={30}>
      <Progress type="circle" percent={50} />
      <Progress type="circle" percent={50} size="small" />
      <Progress type="circle" percent={50} size={20} />
    </Flex>
    <Flex align="center" wrap gap={30}>
      <Progress type="dashboard" percent={50} />
      <Progress type="dashboard" percent={50} size="small" />
      <Progress type="dashboard" percent={50} size={20} />
    </Flex>
    <Flex align="center" wrap gap={30}>
      <Progress steps={3} percent={50} />
      <Progress steps={3} percent={50} size="small" />
      <Progress steps={3} percent={50} size={20} />
      <Progress steps={3} percent={50} size={[20, 30]} />
    </Flex>
  </Flex>
);

export default App;

진행률 값 위치 변경 (Change progress value position)

진행률 값의 위치를 바꿀 수 있어요. percentPosition으로 진행률 바 값이 바 안쪽, 바깥쪽, 또는 바 아래쪽에 오도록 조정할 수 있어요.

import React from 'react';
import { Flex, Progress } from 'antd';

const App: React.FC = () => (
  <Flex gap="small" vertical>
    <Progress
      percent={0}
      percentPosition={{ align: 'center', type: 'inner' }}
      size={[200, 20]}
      strokeColor="#E6F4FF"
    />
    <Progress percent={10} percentPosition={{ align: 'center', type: 'inner' }} size={[300, 20]} />
    <Progress
      percent={50}
      percentPosition={{ align: 'start', type: 'inner' }}
      size={[300, 20]}
      strokeColor="#B7EB8F"
    />
    <Progress
      percent={60}
      percentPosition={{ align: 'end', type: 'inner' }}
      size={[300, 20]}
      strokeColor="#001342"
    />
    <Progress percent={100} percentPosition={{ align: 'center', type: 'inner' }} size={[400, 20]} />
    <Progress percent={60} percentPosition={{ align: 'start', type: 'outer' }} />
    <Progress percent={100} percentPosition={{ align: 'start', type: 'outer' }} />
    <Progress percent={60} percentPosition={{ align: 'center', type: 'outer' }} size="small" />
    <Progress percent={100} percentPosition={{ align: 'center', type: 'outer' }} />
  </Flex>
);

export default App;

시맨틱 DOM 스타일링 (Custom semantic dom styling)

classNames와 styles로 객체 또는 함수를 전달해 Progress의 시맨틱 DOM 스타일을 커스터마이즈할 수 있어요.

import React from 'react';
import { Flex, Progress } from 'antd';
import type { GetProp, ProgressProps } from 'antd';

const classNames: ProgressProps['classNames'] = {
  root: 'demo-progress-root',
  rail: 'demo-progress-rail',
  track: 'demo-progress-track',
};

const stylesFn: ProgressProps['styles'] = (info): GetProp<ProgressProps, 'styles', 'Return'> => {
  const percent = info?.props?.percent ?? 0;
  const hue = 200 - (200 * percent) / 100;
  return {
    track: {
      backgroundImage: `
        linear-gradient(
          to right,
          hsla(${hue}, 85%, 65%, 1),
          hsla(${hue + 30}, 90%, 55%, 0.95)
        )`,
      borderRadius: 8,
      transition: 'all 0.3s ease',
    },
    rail: {
      backgroundColor: 'rgba(0, 0, 0, 0.1)',
      borderRadius: 8,
    },
  };
};

const App: React.FC = () => (
  <Flex vertical gap="large">
    <Progress classNames={classNames} styles={stylesFn} percent={10} />
    <Progress classNames={classNames} styles={stylesFn} percent={20} />
    <Progress classNames={classNames} styles={stylesFn} percent={40} />
    <Progress classNames={classNames} styles={stylesFn} percent={60} />
    <Progress classNames={classNames} styles={stylesFn} percent={80} />
    <Progress classNames={classNames} styles={stylesFn} percent={99} />
  </Flex>
);

export default App;

API

공통 props는 Common props를 참고해요.

모든 타입이 공유하는 속성이에요.

속성 (Property)	설명 (Description)	타입 (Type)	기본값 (Default)	버전 (Version)	글로벌 설정
classNames	컴포넌트 내부의 각 시맨틱 구조에 대한 class를 지정해요. 객체 또는 함수를 지원해요.	Record<SemanticDOM, string> \| (info: { props })=> Record<SemanticDOM, string>	-	6.0.0	6.0.0
format	콘텐츠의 템플릿 함수	function(percent, successPercent)	(percent) => percent + `%`	-	×
percent	완료 비율을 설정해요.	number	0	-	×
railColor	채워지지 않은 부분의 색	string	-	-	×
showInfo	진행률 값과 상태 아이콘을 표시할지 여부	boolean	true	-	×
status	Progress 상태를 설정해요. 옵션: `success` `exception` `normal` `active`(line만)	string	-	-	×
strokeColor	진행률 바의 색	string	-	-	×
strokeLinecap	진행률 선 끝 모양 스타일	`round` \| `butt` \| `square`, stroke-linecap 참고	`round`	-	×
styles	컴포넌트 내부의 각 시맨틱 구조에 대한 인라인 스타일을 지정해요. 객체 또는 함수를 지원해요.	Record<SemanticDOM, CSSProperties> \| (info: { props })=> Record<SemanticDOM, CSSProperties>	-	6.0.0	6.0.0
success	성공 진행률 바 설정	{ percent: number, strokeColor: string }	-	-	×
~~trailColor~~	채워지지 않은 부분의 색이에요. `railColor`를 대신 사용해 주세요.	string	-	-	×
type	타입 설정. 옵션: `line` `circle` `dashboard`	string	`line`	-	×
size	Progress 크기	number \| [number \| string, number] \| { width: number, height: number } \| "small" \| "medium"	"medium"	5.3.0, Object: 5.18.0	×

`type="line"`

속성 (Property)	설명 (Description)	타입 (Type)	기본값 (Default)	버전 (Version)
steps	총 단계 수	number	-	-
rounding	값을 반올림하는 함수	(step: number) => number	Math.round	5.24.0
strokeColor	진행률 바의 색이에요. 객체를 전달하면 `linear-gradient`로 렌더링하고, `steps`가 있으면 `string[]`을 받을 수 있어요.	string \| string[] \| { from: string; to: string; direction: string }	-	4.21.0: `string[]`
percentPosition	진행률 값 위치예요. 객체로 전달하며, `align`은 값의 가로 위치, `type`은 값이 바 안쪽인지 바깥쪽인지 나타내요.	{ align: string; type: string }	{ align: "end", type: "outer" }	5.18.0

`type="circle"`

속성 (Property)	설명 (Description)	타입 (Type)	기본값 (Default)	버전 (Version)
steps	총 단계 수예요. 객체를 전달하면 `count`는 단계 수, `gap`은 단계 사이 거리예요. 숫자를 전달하면 `gap` 기본값은 2예요.	number \| { count: number, gap: number }	-	5.16.0
strokeColor	원형 진행률의 색이에요. 객체를 전달하면 그라데이션을 렌더링해요.	string \| { number%: string }	-	-
strokeWidth	원형 진행률의 너비를 설정해요. 단위: 캔버스 너비의 백분율	number	6	-

`type="dashboard"`

속성 (Property)	설명 (Description)	타입 (Type)	기본값 (Default)	버전 (Version)
steps	총 단계 수예요. 객체를 전달하면 `count`는 단계 수, `gap`은 단계 사이 거리예요. 숫자를 전달하면 `gap` 기본값은 2예요.	number \| { count: number, gap: number }	-	5.16.0
gapDegree	반원의 gap 각도, 0 ~ 295	number	75	-
gapPlacement	gap 배치. 옵션: `top` `bottom` `start` `end`	string	`bottom`	-
~~gapPosition~~	gap 위치. 옵션: `top` `bottom` `left` `right`. `gapPlacement`를 대신 사용해 주세요.	string	`bottom`	-
strokeWidth	대시보드 진행률의 너비를 설정해요. 단위: 캔버스 너비의 백분율	number	6	-

시맨틱 DOM (Semantic DOM)

시맨틱 DOM 구조는 https://ant.design/components/progress/semantic.md 에서 확인할 수 있어요.

디자인 토큰 (Design Token)

컴포넌트 토큰 (Progress) (Component Token)

토큰 이름 (Token Name)	설명 (Description)	타입 (Type)	기본값 (Default Value)
circleIconFontSize	원형 진행률 바의 아이콘 크기	string	1.1666666666666667em
circleTextColor	원형 진행률 바의 텍스트 색	string	rgba(0,0,0,0.88)
circleTextFontSize	원형 진행률 바의 텍스트 크기	string	1em
defaultColor	진행률 바의 기본 색	string	#1677ff
lineBorderRadius	선형 진행률 바의 테두리 반경	number	100
remainingColor	진행률 바의 남은 부분 색	string	rgba(0,0,0,0.06)

글로벌 토큰 (Global Token)

토큰 이름 (Token Name)	설명 (Description)	타입 (Type)
colorBgContainer	컨테이너 배경색이에요. 기본 버튼, 입력 상자 등. `colorBgElevated`와 혼동하지 마세요.	string
colorError	오류 Button, 오류 Result 컴포넌트 등 작업 실패의 시각적 요소를 나타내는 데 사용돼요.	string
colorSuccess	Result, Progress 등 작업 성공의 토큰 시퀀스를 나타내는 데 사용돼요.	string
colorText	W3C 표준을 따르는 기본 텍스트 색이에요. 가장 어두운 중성색이기도 해요.	string
colorWhite	테마에 의해 변경되지 않는 순수한 흰색	string
fontFamily	Ant Design의 글꼴은 시스템의 기본 인터페이스 글꼴을 우선시하고, 화면 표시에 적합한 대체 글꼴 라이브러리를 제공해 플랫폼과 브라우저에 따라 가독성을 유지하며 친근하고 안정적이며 전문적인 특성을 반영해요.	string
fontSize	디자인 시스템에서 가장 널리 쓰이는 글자 크기로, 여기서 텍스트 그라데이션이 파생돼요.	number
fontSizeSM	작은 글자 크기	number
lineHeight	텍스트의 줄 높이예요.	number
marginXS	작은 크기의 요소 여백을 제어해요.	number
marginXXS	가장 작은 크기의 요소 여백을 제어해요.	number
motionDurationSlow	동작 속도, 느린 속도예요. 큰 요소의 애니메이션 상호작용에 사용돼요.	string
motionEaseInOutCirc	미리 정의된 모션 곡선이에요.	string
motionEaseOutQuint	미리 정의된 모션 곡선이에요.	string
paddingXXS	요소의 아주 작은 패딩을 제어해요.	number

진행률