# Progress Guides
## Patterns
### Async Task Progress
When to use:
- A task advances over time toward completion.
Composition notes:
- Keep the bar paired with explanatory text.
- Use determinate values only when they reflect real task state.
Trade-offs:
- Strong sense of progress.
- Misleading if the values are only guessed.
```tsx
import { Button, Progress, ProgressTrack, Text } from '@vega-ui/react';
import { useEffect, useId, useState } from 'react';
export default function ParentOwnedUploadProgress() {
const labelId = useId();
const [percent, setPercent] = useState(0);
const [running, setRunning] = useState(false);
const done = percent === 100;
const uploading = running && !done;
useEffect(() => {
if (!uploading) return;
const timer = setInterval(() => {
setPercent((current) => Math.min(current + 4, 100));
}, 200);
return () => clearInterval(timer);
}, [uploading]);
let status = 'Ready to upload';
if (done) {
status = 'Upload complete';
} else if (uploading) {
status = 'Uploading…';
} else if (percent > 0) {
status = `Paused at ${percent}%`;
}
const reset = () => {
setRunning(false);
setPercent(0);
};
return (
product-demo.mp4 · 48 MB{percent}%
{status}
);
}
```
### Indeterminate Operation
When to use:
- Work is happening but the completion amount is unknown.
Composition notes:
- Distinguish the state clearly from determinate progress.
- Keep nearby copy explicit about the running operation.
Trade-offs:
- Better than fake percentages.
- Less informative than determinate progress.
```tsx
import { Button, Progress, ProgressTrack, Text } from '@vega-ui/react';
import { useEffect, useId, useState } from 'react';
type Phase = 'idle' | 'preparing' | 'importing' | 'done';
export default function IndeterminateProgress() {
const labelId = useId();
const [phase, setPhase] = useState('idle');
const [total, setTotal] = useState(0);
const [imported, setImported] = useState(0);
useEffect(() => {
if (phase !== 'preparing') return;
const timer = setTimeout(() => {
setTotal(3482);
setImported(0);
setPhase('importing');
}, 1800);
return () => clearTimeout(timer);
}, [phase]);
useEffect(() => {
if (phase !== 'importing') return;
const timer = setTimeout(() => {
const next = Math.min(imported + 211, total);
setImported(next);
if (next === total) setPhase('done');
}, 100);
return () => clearTimeout(timer);
}, [phase, imported, total]);
const preparing = phase === 'preparing';
let status = 'Import contacts from contacts.vcf';
if (preparing) {
status = 'Reading file…';
} else if (phase === 'importing') {
status = `Importing ${imported} of ${total} contacts`;
} else if (phase === 'done') {
status = `${total} contacts imported`;
}
return (
{status}
);
}
```
### Embedded Progress In Overlays
When to use:
- A dialog or sheet owns a running operation.
Composition notes:
- Keep the progress local to the task that owns it.
- Use full width when the overlay layout supports it.
Trade-offs:
- Keeps feedback close to the running operation.
- Can feel visually heavy if stacked with too many status indicators.
```tsx
import {
Button,
Dialog,
DialogClose,
DialogContent,
DialogTrigger,
Heading,
Icon,
IconButton,
Progress,
ProgressTrack,
Text,
} from '@vega-ui/react';
import { XIcon } from '@vega-ui/icons';
import { CSSProperties, useEffect, useId, useState } from 'react';
const total = 1240;
export default function ProgressInsideADialog() {
const titleId = useId();
const [open, setOpen] = useState(false);
const [exported, setExported] = useState(0);
const running = open && exported < total;
useEffect(() => {
if (!running) return;
const timer = setInterval(() => {
setExported((current) => Math.min(current + 62, total));
}, 150);
return () => clearInterval(timer);
}, [running]);
const changeOpen = (next: boolean) => {
setOpen(next);
if (next) setExported(0);
};
return (
);
}
```
## Comparison
### Quick Decision Rule
Use `Progress` when the value represents ongoing completion over time.
### `Progress` vs `Meter`
Use `Progress` when:
- the value represents task completion or async advancement
Use `Meter` when:
- the value is a bounded measurement or score
Main trade-off: progress is temporal completion, while meter is descriptive measurement.
### `Progress` vs `Spinner`
Use `Progress` when:
- some notion of completion amount can be shown
Use `Spinner` when:
- only indefinite loading feedback is available
Main trade-off: progress communicates amount, while spinner communicates activity without range.
### `Progress` vs `MeterStack`
Use `Progress` when:
- one completion signal is enough
Use `MeterStack` when:
- the value is composed of several meaningful parts rather than one completion amount
### Choose This Component When
- A task is moving toward completion.
- A value can represent completion over time.
- A determinate or indeterminate bar is the right mental model.
- the bar should read as progress rather than descriptive measurement
### Do Not Choose This Component When
- The value is a static score or capacity measurement.
- No bar-like completion model exists.
- A spinner would better match the uncertainty of the state.
## Troubleshooting
### Progress Should Probably Be A Meter
#### Symptom
The bar renders, but the value is really a score, quota, or capacity rather than task completion.
#### Likely Cause
`Progress` was chosen for a descriptive measurement instead of a temporal completion model.
#### How To Verify
- Ask whether the value changes toward completion over time.
#### Fix
- Switch to `Meter` for bounded descriptive measurements.
### Users Do Not Know What Is Progressing
#### Symptom
The bar is visible, but users cannot tell which task it represents.
#### Likely Cause
The component was rendered without explanatory text context.
#### How To Verify
- Hide nearby headings and inspect whether the progress meaning is still obvious.
#### Fix
- Add nearby text that describes the running task.
### Determinate Progress Feels Untrustworthy
#### Symptom
The percentages move strangely or stop matching the real operation.
#### Likely Cause
The displayed values do not reflect real completion state.
#### How To Verify
- Compare the shown value with actual task milestones.
#### Fix
- Use real progress values.
- Switch to indeterminate mode when exact progress is unavailable.