Progress

A display-only determinate progress indicator — you know the current position along a known total (upload bytes, wizard step, quiz completion, download percentage). Ships two visual flavors on the same primitive: horizontal linear bar and circular SVG arc.

import { Progress } from '@dashforge/tw';

<Progress value={40} fullWidth showLabel />

Progress vs Spinner

Two primitives that look superficially similar but mean different things — pick by whether you know how far along the operation is.

Progress carries role="progressbar" + aria-valuenow/min/max. Spinner is role="status" + aria-busy="true". Two different a11y contracts, two different UX contracts.

If your operation starts unknown-ETA and later becomes known-ETA (e.g. resumable upload that first probes the server), start with <Spinner> and swap to <Progress> when the ETA lands.

Quick Start

import { Progress } from '@dashforge/tw';

// Simple percentage with the default formatter (rounded %).
<Progress value={40} fullWidth showLabel />

// Wizard step counter with a custom label.
<Progress
  value={3}
  max={5}
  fullWidth
  showLabel
  formatLabel={(v, max) => `Step ${v} of ${max}`}
  thickness="thick"
/>

// Circular flavor for KPI / dashboard tiles.
<Progress variant="circular" value={78} size="lg" showLabel />

Examples

Linear variant

Default flavor. showLabel opts into the % label next to the bar. thickness controls the track height on top of size.

import { Progress, Stack, Typography } from '@dashforge/tw';

<Stack gap={4}>
  <Progress value={40} fullWidth />
  <Progress value={72} fullWidth showLabel />
  <Progress
    value={3}
    max={5}
    fullWidth
    showLabel
    formatLabel={(v, max) => `Step ${v} of ${max}`}
    thickness="thick"
  />
  {/* 6 colour intents */}
  <Progress value={60} fullWidth color="primary" />
  <Progress value={60} fullWidth color="secondary" />
  <Progress value={60} fullWidth color="success" />
  <Progress value={60} fullWidth color="warning" />
  <Progress value={60} fullWidth color="danger" />
  <Progress value={60} fullWidth color="neutral" />
</Stack>

Circular variant

SVG arc, drawn starting at 12 o'clock and filling clockwise for the current ratio. The value label renders in the center of the arc when showLabel is set.

import { Progress, Stack } from '@dashforge/tw';

<Stack direction="row" gap={4}>
  <Progress variant="circular" value={60} size="sm" showLabel />
  <Progress variant="circular" value={60} size="md" showLabel />
  <Progress variant="circular" value={60} size="lg" showLabel />
</Stack>

{/* Custom label + colour */}
<Progress
  variant="circular"
  value={82}
  size="lg"
  thickness="thick"
  showLabel
  formatLabel={(v) => `${v}pt`}
  color="success"
/>

Upload scenario — value + visibleWhen

Real-world case: value drives the bar during an active upload, and visibleWhen gates the entire component so it disappears when idle. The closure reads local state (state !== 'idle') with no DashForm in scope — that's supported natively, the predicate is just a JS closure.

import { useEffect, useState } from 'react';
import { Button, Progress, Stack } from '@dashforge/tw';

function UploadDemo() {
  const totalBytes = 12 * 1024 * 1024; // 12 MB
  const [uploaded, setUploaded] = useState(0);
  const [state, setState] = useState<'idle' | 'uploading' | 'done'>('idle');

  useEffect(() => {
    if (state !== 'uploading') return;
    // ... animate uploaded from 0 to totalBytes over ~4s
  }, [state]);

  return (
    <Stack gap={3}>
      <Button onClick={() => setState('uploading')}>Start upload</Button>

      <Progress
        value={uploaded}
        max={totalBytes}
        fullWidth
        showLabel
        formatLabel={(v, max) =>
          `${(v / 1_048_576).toFixed(1)} MB / ${(max / 1_048_576).toFixed(1)} MB`
        }
        color={state === 'done' ? 'success' : 'primary'}
        // Hidden while idle — closure reads local state without a DashForm.
        visibleWhen={() => state !== 'idle'}
      />
    </Stack>
  );
}

Theme defaults

Configure <Progress> defaults application-wide via Option C.

import { patchTheme } from '@dashforge/tw-theme';

patchTheme({
  components: {
    Progress: {
      defaults: {
        variant:   'linear',
        color:     'primary',
        size:      'md',
        fullWidth: true,
      },
    },
  },
});

Configurable axes (ProgressVariantProps):

Precedence chain (lowest → highest):

1. TV defaultVariants (variant='linear', color='primary', size='md', fullWidth=false).
2. theme.components.Progress.defaults.
3. Instance props.
4. sx — appended to the root class chain via tailwind-merge.

Same chain applies to slotProps (theme slotProps → instance slotProps).

API

Props

Slots & slotProps

<Progress> renders through named slots. Each accepts a { className?: string } override via slotProps.

Notes

• Value required, no indeterminate mode: Progress needs a numeric value — if you don't have one, reach for <Spinner>. This isn't API bloat: <Spinner> and <Progress> map to role="status" (busy) and role="progressbar" (making-progress) respectively, and screen readers announce them differently. They're two different UX contracts.
• Value clamped internally: passing value > max or value < min doesn't throw — the component clamps to the bounds. The aria-valuenow reflects the clamped value, not the raw prop.
• visibleWhen is a closure (catalog-uniform pattern): the predicate can freely mix engine state (via the argument) and local state / context / refs captured in the outer scope. React re-render cascade guarantees fresh values on every evaluation. No useMemo needed.
• access is orthogonal to bridge integration: Progress is display-only (no form registration), but access still works via the RBAC context — useful for gating a metrics Progress bar to admin roles.
• Circular arc starts at 12 o'clock: SVG's default origin is 3 o'clock; we transform: rotate(-90deg) the SVG so the fill starts at the top and grows clockwise, which is the near-universal convention.
• Motion-reduce safe: the linear bar width and the circular arc stroke-dashoffset both use CSS transitions gated on prefers-reduced-motion — users who opt out see instantaneous updates without animation.
• Not a form field: Progress does NOT register on the form bridge, does NOT write to bridge.setValue, does NOT appear in the form data on submit. If you need a numeric input the user can drag, use <Slider>.
• When to switch to <Slider>: if the value should be user-editable (drag / keyboard), it's a Slider — Progress is display-only.
• When to switch to <Spinner>: if the ETA is unknown, it's a Spinner — Progress requires a value.