> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/en/components/progress.html

> 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.

# Progress

Display task completion.


## Basic usage

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


45%

basic.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/progress/basic.tsx"
import { Progress } from '@ifhover/leaf-ui';

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

Expand code


## Examples

### Progress states

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


In progress

45%

Complete

Failed

states.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/progress/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>
  );
}
```

Expand code

### Indeterminate progress

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


indeterminate.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/progress/indeterminate.tsx"
import { Progress } from '@ifhover/leaf-ui';

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

Expand code

### Circular progress

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


45%

circles.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/progress/circles.tsx"
import { Progress } from '@ifhover/leaf-ui';

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

Expand code

[](#)
### Updating progress

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


45%

DecreaseIncrease

controlled.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/progress/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>
  );
}
```

Expand code

### Stepped progress

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


60%

steps.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/progress/steps.tsx"
import { Progress } from '@ifhover/leaf-ui';

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

Expand code

### 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

Copy code

```tsx lineNumbers file="../../../src/examples/en/progress/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' },
      ]}
    />
  );
}
```

Expand code

### Dashboard

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


65%

dashboard.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/progress/dashboard.tsx"
import { Progress } from '@ifhover/leaf-ui';

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

Expand code


## API

### Progress API

Configure the progress percentage, status and presentation.

| Property         | Type                                                 | Default    | Description                                                                                               |
| ---------------- | ---------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------- |
| `percent`        | `number`                                             | `0`        | Completion 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.                                      |
| `showInfo`       | `boolean`                                            | `true`     | Show percentage or status icon                                                                            |
| `format`         | `(percent: number) => ReactNode`                     | —          | Custom progress text                                                                                      |
| `strokeWidth`    | `number`                                             | —          | Stroke width; pixels for lines, view units for circles                                                    |
| `color`          | `string`                                             | —          | Custom progress color                                                                                     |
| `size`           | `number`                                             | `100`      | Circular diameter in pixels                                                                               |
| `indeterminate`  | `boolean`                                            | `false`    | Animated loading when the total progress is unknown; no percentage                                        |
| `active`         | `boolean`                                            | `false`    | Shimmer inside an unfinished line; true enables it. Completed, failed and indeterminate progress omit it. |
| `trailColor`     | `string`                                             | —          | Track color                                                                                               |
| `segments`       | `readonly `[`ProgressSegment`](#progresssegment)`[]` | —          | Display multiple sections with proportions and colors.                                                    |
| `steps`          | `number`                                             | —          | Number of discrete progress steps.                                                                        |
| `dashboard`      | `boolean`                                            | `false`    | Display progress as a dashboard gauge.                                                                    |
| `successPercent` | `number`                                             | —          | Part of the progress completed successfully.                                                              |

### ProgressSegment

Describe the percentage and color of one progress segment.

| Property  | Type     | Default  | Description                |
| --------- | -------- | -------- | -------------------------- |
| `key`     | `string` | —        | Stable, unique identifier. |
| `percent` | `number` | Required | Completion percentage.     |
| `color`   | `string` | —        | Color or semantic tone.    |
