For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/en/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/en/llms-full.txt, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/en/components/progress.md.

Progress

Display task completion.

Basic usage

Pass the completion percentage as percent and identify the task with aria-label.

45%
basic.tsx
import { Progress } from '@ifhover/leaf-ui';

export function ProgressBasic() {
  return <Progress percent={45} aria-label="Upload progress" />;
}

Examples

Progress states

Reaching 100 automatically shows success. Set status="error" when a task fails.

In progress
45%
Complete
Failed
states.tsx
import { Flex, Progress, Space, Text } from '@ifhover/leaf-ui';

export function ProgressStates() {
  return (
    <Space direction="vertical" align="stretch">
      <Flex direction="column" gap="sm">
        <Text tone="muted">In progress</Text>
        <Progress percent={45} aria-label="Task in progress" />
      </Flex>
      <Flex direction="column" gap="sm">
        <Text tone="muted">Complete</Text>
        <Progress percent={100} aria-label="Completed task" />
      </Flex>
      <Flex direction="column" gap="sm">
        <Text tone="muted">Failed</Text>
        <Progress percent={70} status="error" aria-label="Failed task" />
      </Flex>
    </Space>
  );
}

Indeterminate progress

Use indeterminate when the total progress cannot be calculated. No numeric percentage is displayed or exposed in this mode.

indeterminate.tsx
import { Progress } from '@ifhover/leaf-ui';

export function ProgressIndeterminate() {
  return <Progress indeterminate aria-label="Processing files" />;
}

Circular progress

Use type="circle" for a circular indicator and percent for the completion percentage.

45%
circles.tsx
import { Progress } from '@ifhover/leaf-ui';

export function ProgressCircles() {
  return <Progress type="circle" percent={45} aria-label="Upload progress" />;
}

Updating progress

The application updates progress; the component does not advance it automatically. Set active={false} to disable the shimmer on line progress.

45%
controlled.tsx
import { Button, Flex, Progress, Space } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function ProgressControlled() {
  const [percent, setPercent] = useState(45);

  return (
    <Space direction="vertical" align="stretch">
      <Progress percent={percent} aria-label="Upload progress" />
      <Flex gap="md" align="center" wrap>
        <Button
          variant="outline"
          disabled={percent === 0}
          onClick={() => setPercent((current) => Math.max(0, current - 10))}
        >
          Decrease
        </Button>
        <Button
          disabled={percent === 100}
          onClick={() => setPercent((current) => Math.min(100, current + 10))}
        >
          Increase
        </Button>
      </Flex>
    </Space>
  );
}

Stepped progress

steps divides the track into a fixed number of steps. percent still represents the completion percentage.

60%
steps.tsx
import { Progress } from '@ifhover/leaf-ui';

export function ProgressSteps() {
  return <Progress percent={60} steps={10} aria-label="Review progress" />;
}

Segmented progress

Each segments percentage is relative to the full track. Also set percent to the sum of the completed segments for the overall value.

75%
segments.tsx
import { Progress } from '@ifhover/leaf-ui';

export function ProgressSegments() {
  return (
    <Progress
      percent={75}
      aria-label="File processing progress"
      segments={[
        { key: 'processed', percent: 35, color: '#1e964f' },
        { key: 'uploaded', percent: 40, color: '#1d9bf0' },
      ]}
    />
  );
}

Dashboard

Set dashboard on a circular indicator to show progress as a dashboard.

65%
dashboard.tsx
import { Progress } from '@ifhover/leaf-ui';

export function ProgressDashboard() {
  return <Progress type="circle" dashboard percent={65} aria-label="Capacity usage" />;
}

API

Progress API

Configure the progress percentage, status and presentation.

PropertyTypeDefaultDescription
percentnumber0Completion percentage, from 0 to 100
type'line' | 'circle''line'Line or circular progress
status'normal' | 'success' | 'error''normal'Progress state; normal becomes success at 100% unless indeterminate.
showInfobooleantrueShow percentage or status icon
format(percent: number) => ReactNode—Custom progress text
strokeWidthnumber—Stroke width; pixels for lines, view units for circles
colorstring—Custom progress color
sizenumber100Circular diameter in pixels
indeterminatebooleanfalseAnimated loading when the total progress is unknown; no percentage
activebooleanfalseShimmer inside an unfinished line; true enables it. Completed, failed and indeterminate progress omit it.
trailColorstring—Track color
segmentsreadonly ProgressSegment[]—Display multiple sections with proportions and colors.
stepsnumber—Number of discrete progress steps.
dashboardbooleanfalseDisplay progress as a dashboard gauge.
successPercentnumber—Part of the progress completed successfully.

ProgressSegment

Describe the percentage and color of one progress segment.

PropertyTypeDefaultDescription
keystring—Stable, unique identifier.
percentnumberRequiredCompletion percentage.
colorstring—Color or semantic tone.