# Progress

> Shows how far a task with a known length has come.

A progress bar shows how far a task of known length has come, such as uploading a master file.

## When to use

- Use it for uploads, imports and other tasks that report a percentage.
- Use a [Spinner](https://design.sosialoka.tech/components/spinner/) when the length is unknown.
- Always show a label above the bar, and the percentage when it helps.

_Live preview of the React and Vue versions: https://design.sosialoka.tech/components/progress/_

## Anatomy

1. Label
2. Value
3. Track
4. Indicator

A label and an optional value above an 8px (`h-2`) pill track on `muted`, filled with `primary` up to the value.

## Variants

There is one style.

## Props

| React | Vue | Flutter | Type | Default | Use |
| --- | --- | --- | --- | --- | --- |
| `value` | `model-value` | `value` (0 to 1) | number | React: none, which makes the bar indeterminate; Vue: `0` | How far the task has come, 0 to 100 on the web. |
| `ProgressLabel` | `aria-labelledby` on a visible label | `semanticsLabel` | text | none | Names the task. |
| `ProgressValue` | text beside the label | `semanticsValue` | text | none | Shows the percentage. |

## Code

**React**
```tsx
import { Progress, ProgressLabel, ProgressValue } from "@/components/ui/progress"

export default function ProgressDemo() {
  return (
    <Progress value={64} className="w-full max-w-sm">
      <ProgressLabel>Mengunggah master.wav</ProgressLabel>
      <ProgressValue />
    </Progress>
  )
}
```

**Vue**
```vue
<script setup lang="ts">
import { useId } from "vue"
import { Progress } from "@/components/ui/progress"

const id = useId()
</script>

<template>
  <div class="grid w-full max-w-sm gap-3">
    <div class="flex text-sm">
      <span :id="`${id}-label`" class="font-medium">Mengunggah master.wav</span>
      <span class="ml-auto text-muted-foreground tabular-nums">64%</span>
    </div>
    <Progress :model-value="64" :aria-labelledby="`${id}-label`" />
  </div>
</template>
```

**Flutter**
```dart
import 'package:flutter/widgets.dart';
import 'package:shadcn_ui/shadcn_ui.dart';

class ProgressDemo extends StatelessWidget {
  const ProgressDemo({super.key});

  @override
  Widget build(BuildContext context) {
    final theme = ShadTheme.of(context);
    return ConstrainedBox(
      constraints: const BoxConstraints(maxWidth: 384),
      child: Column(
        mainAxisSize: MainAxisSize.min,
        spacing: 12,
        children: [
          Row(
            children: [
              Text('Mengunggah master.wav', style: theme.textTheme.small),
              const Spacer(),
              Text('64%', style: theme.textTheme.muted),
            ],
          ),
          ShadProgress(value: 0.64, minHeight: 8, semanticsLabel: 'Mengunggah master.wav', semanticsValue: '64%'),
        ],
      ),
    );
  }
}
```

## Install

**React**
```bash
npx shadcn@latest add https://design.sosialoka.tech/r/react/progress.json
```

**Vue**
```bash
npx shadcn-vue@latest add https://design.sosialoka.tech/r/vue/progress.json
```

## Accessibility

- It has `role="progressbar"` with `aria-valuenow`, `aria-valuemin` and `aria-valuemax`.
- Name it with its visible label.
- Don't announce every percent; say when the task is done, for example with a toast.
