# Progress

## Overview

A visual indicator of completion or percentage. Renders a horizontal bar filled to a given percentage. It is purely display-only — for interactive value selection, use `<Slider>`.

---

## When to Use

- Upload or download completion
- Onboarding completion percentage
- Task or project progress indicators
- Step completion within a multi-step form

## When NOT to Use

- Interactive range selection — use `<Slider>`.
- Step-by-step processes — use `<Stepper>`.

---

## Variants

| Variant       | Color   | Usage                    |
| ------------- | ------- | ------------------------ |
| `default`     | Primary | General progress         |
| `success`     | Green   | Completed or successful  |
| `info`        | Blue    | Informational progress   |
| `warning`     | Amber   | Nearing limit or caution |
| `destructive` | Red     | Critical or failed state |

---

## Props

| Prop        | Type                                                             | Default     | Required | Description            |
| ----------- | ---------------------------------------------------------------- | ----------- | -------- | ---------------------- |
| `value`     | `number`                                                         | —           | **Yes**  | Progress value (0–100) |
| `variant`   | `'default' \| 'success' \| 'info' \| 'warning' \| 'destructive'` | `'default'` | No       | Semantic color variant |
| `className` | `string`                                                         | —           | No       | Additional CSS classes |

---

## Examples

### Basic Progress Bar

```tsx
import { Progress } from 'xertica-ui/ui';

<Progress value={65} />;
```

### With Label

```tsx
<div className="space-y-2">
  <div className="flex justify-between text-sm">
    <span>Upload Progress</span>
    <span>65%</span>
  </div>
  <Progress value={65} />
</div>
```

### Semantic Variants

```tsx
<Progress value={100} variant="success" />
<Progress value={60} variant="info" />
<Progress value={75} variant="warning" />
<Progress value={30} variant="destructive" />
```

### Animated (within a useEffect)

```tsx
const [value, setValue] = useState(0);

useEffect(() => {
  const timer = setTimeout(() => setValue(66), 500);
  return () => clearTimeout(timer);
}, []);

<Progress value={value} />;
```

---

## AI Rules

- `value` must be between 0 and 100.
- Always pair with a visible label showing the percentage — the bar alone is difficult to interpret.
- Use `variant` to communicate semantic state: `success` when complete, `warning` when nearing a limit, `destructive` for failures.
- The `Progress` bar does not have an interactive thumb — never confuse it with `Slider`.

---

## Related Components

- [`Slider`](./slider.md) — For interactive range selection
- [`Stepper`](./stepper.md) — For multi-step process indication