---
title: "Progress"
description: "Measures how much is left of a task with a known end. A numeric value is determinate; null communicates ongoing work without a percentage."
kind: component
id: C-020
registry: "progress"
docs: "https://koten.codehive.com.co/components/progress"
markdown: "https://koten.codehive.com.co/md/components/progress.md"
install: "npx shadcn@latest add https://koten.codehive.com.co/r/progress.json"
language: en
---

# Progress · 進捗

> Component C-020 in the Koten UI catalog.

Measures how much is left of a task with a known end. A numeric value is determinate; null communicates ongoing work without a percentage.

> Japanese labels in this page are documentation metadata. Keep the consumer UI in the product's language and do not add Japanese decoration unless the user asks (R-031).

## Install

Install `koten-theme` first when the project does not have Koten tokens yet. Use the runner of your project.

```bash
# Node
npx shadcn@latest add https://koten.codehive.com.co/r/progress.json

# Bun
bunx shadcn@latest add https://koten.codehive.com.co/r/progress.json
```

## Files

- `@/components/ui/progress.tsx`
- `@/lib/koten/cn.ts`
- `@/lib/koten/format.ts`
- `@/lib/koten/intl.ts`
- `@/lib/koten/labels.ts`
- `@/lib/koten/provider.tsx`

## Reference

- Upstream primitive: https://base-ui.com/react/components/progress

## Examples

### Determinate progress

Value and max define the bar; the tone only reinforces the outcome.

```tsx
<Progress label="Export" value={65} />
<Progress label="Import" value={100} tone="success" />
```

### Indeterminate progress

value={null} declares there is no percentage: use it until the server returns a total.

```tsx
<Progress label="Sync" value={null} tone="primary" />
```

## Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `label` | `ReactNode` | `requerido` | Name of the task; Base UI associates it with the bar. |
| `value` | `number \| null` | `requerido` | null means indeterminate; no false percentage is announced. |
| `max` | `number` | `100` | Total of the run; change it when the task is measured in units. |
| `tone` | `primary \| success \| warning \| danger` | `primary` | Indicator color; the state must also live in the text. |
| `showValue` | `boolean` | `true` | Shows the numeric value next to the label; the value stays exposed to screen readers. |
| `className` | `string` | `—` | Adjusts the block width; do not change the track height. |

## Accessibility

- Base UI exposes role progressbar with aria-valuenow, aria-valuemin and aria-valuemax; the label is associated.
- With value={null} the state is indeterminate and no invented percentage is announced.
- Color is not enough: the label and visible value identify the task and its advance.

## Sources

- Catalog page: https://koten.codehive.com.co/components/progress
- Markdown: https://koten.codehive.com.co/md/components/progress.md
- Repository: https://github.com/codehive-colombia/koten