Progress

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.

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(() => {

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.

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<Phase>('idle');
  const [total, setTotal] = useState(0);
  const [imported, setImported] = useState(0);

  useEffect(() => {

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.

import {
  Button,
  Dialog,
  DialogClose,
  DialogContent,
  DialogTrigger,
  Heading,
  Icon,
  IconButton,
  Progress,
  ProgressTrack,
  Text,

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.