# Progress

Shows how far a task has advanced.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Progress.tsx)

Figma: [Progress](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=3048-372) (`Progress.Root`)

## Overview

A bar that fills in the `intent` color as a task advances or a measurement nears its limit, with an optional label and printed value.

## Examples

### Basic

```tsx
import { Progress, style } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <Progress.Root value={60} {...styles.progress()}>
      <Progress.Label>Uploading</Progress.Label>
      <Progress.Value />
      <Progress.Track>
        <Progress.Indicator />
      </Progress.Track>
    </Progress.Root>
  )
}

namespace styles {
  export const progress = style({ maxWidth: '24rem !custom' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Progress/Basic.tsx)

### Intent

Set `intent` to `neutral` (default), `positive`, `warning`, or `negative`. Use `warning` and `negative` for a meter that nears or reaches its limit.

```tsx
import { Progress, style } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <div {...styles.stack()}>
      {(['neutral', 'positive', 'warning', 'negative'] as const).map((intent, index) => (
        <Progress.Root intent={intent} key={intent} value={20 + index * 20}>
          <Progress.Label>{intent}</Progress.Label>
          <Progress.Value />
          <Progress.Track>
            <Progress.Indicator />
          </Progress.Track>
        </Progress.Root>
      ))}
    </div>
  )
}

namespace styles {
  export const stack = style({
    display: 'flex',
    flexDirection: 'column',
    gap: '16',
    maxWidth: '24rem !custom',
  })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Progress/Intent.tsx)

### Value

If the remaining work is unknown, pass `value={null}` for an indeterminate bar.

```tsx
import { Progress, style } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <Progress.Root value={null} {...styles.progress()}>
      <Progress.Label>Indeterminate</Progress.Label>
      <Progress.Track>
        <Progress.Indicator />
      </Progress.Track>
    </Progress.Root>
  )
}

namespace styles {
  export const progress = style({ maxWidth: '24rem !custom' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Progress/Value.tsx)

### Meter

If the bar shows a measurement against a limit, such as the share of a spending limit used, pass `role="meter"`. Pass `getAriaValueText` to read the limit too.

```tsx
import { Progress, style } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <div {...styles.stack()}>
      <Progress.Root
        format={{ currency: 'USD', style: 'currency' }}
        getAriaValueText={(value) => `${value} of $100.00 per day`}
        role="meter"
        value={20}
      >
        <Progress.Label>Daily limit</Progress.Label>
        <Progress.Value />
        <Progress.Track>
          <Progress.Indicator />
        </Progress.Track>
      </Progress.Root>
      <Progress.Root
        format={{ currency: 'USD', style: 'currency' }}
        getAriaValueText={(value) => `${value} of $100.00 per week`}
        intent="warning"
        role="meter"
        value={90}
      >
        <Progress.Label>Weekly limit</Progress.Label>
        <Progress.Value />
        <Progress.Track>
          <Progress.Indicator />
        </Progress.Track>
      </Progress.Root>
      <Progress.Root
        format={{ currency: 'USD', style: 'currency' }}
        getAriaValueText={(value) => `${value} of $100.00 per month`}
        intent="negative"
        role="meter"
        value={100}
      >
        <Progress.Label>Monthly limit</Progress.Label>
        <Progress.Value />
        <Progress.Track>
          <Progress.Indicator />
        </Progress.Track>
      </Progress.Root>
    </div>
  )
}

namespace styles {
  export const stack = style({
    display: 'flex',
    flexDirection: 'column',
    gap: '16',
    maxWidth: '24rem !custom',
  })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Progress/Meter.tsx)

## Anatomy

Import the component and assemble its parts.

```tsx
import { Progress } from '@tempoxyz/ds'

<Progress.Root>
  <Progress.Label />
  <Progress.Value />
  <Progress.Track>
    <Progress.Indicator />
  </Progress.Track>
</Progress.Root>
```

## Guidelines

### When to Use

* Report measurable work, such as an upload of a payouts CSV or an export of 1,240 transactions.
* Count through a batch, such as 3 of 5 payments in a payout run.
* Track a long sync with a known end, such as block indexing up to the current height.
* Show an indeterminate bar for a named task of unknown length, such as a bridge deposit confirmation.
* Show the share of a limit used as a meter, such as an app's daily spending limit.

### When Not to Use

* Use [Gauge](/docs/components/gauge) for a measurement in a compact ring, such as storage used.
* Use [Spinner](/docs/components/spinner) for a short wait in a region or control.
* Use [Skeleton](/docs/components/skeleton) for content with a known shape.
* Use `loading` on a [Button](/docs/components/button) while its action runs.
* Use [Stepper](/docs/components/stepper) for a fixed sequence of steps, such as account setup.

### Show Determinate Progress When You Can Measure It

A rough count of steps is enough. Keep `value={null}` for work with no measurable end.

**Do:** Pass a `value` for an upload whose size you know.

```tsx
/**
 * Do example for "Show Determinate Progress When You Can Measure It" on the Progress page.
 * Pass a `value` for an upload whose size you know.
 * @module
 */
import { Progress, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Progress.Root value={60} {...styles.progress()}>
      <Progress.Label>Uploading payouts.csv</Progress.Label>
      <Progress.Value />
      <Progress.Track>
        <Progress.Indicator />
      </Progress.Track>
    </Progress.Root>
  )
}

namespace styles {
  export const progress = style({ maxWidth: '20rem !custom' })
}
```

**Don't:** Show an indeterminate bar for work you can measure.

```tsx
/**
 * Don't example for "Show Determinate Progress When You Can Measure It" on the Progress page.
 * Don't show an indeterminate bar for work you can measure.
 * @module
 */
import { Progress, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Progress.Root value={null} {...styles.progress()}>
      <Progress.Label>Uploading payouts.csv</Progress.Label>
      <Progress.Track>
        <Progress.Indicator />
      </Progress.Track>
    </Progress.Root>
  )
}

namespace styles {
  export const progress = style({ maxWidth: '20rem !custom' })
}
```

### Name the Task

Add `Progress.Value` to print the percentage, or pass it a function child for units, such as 3 of 5 files. Without a visible label, pass `aria-label`.

**Do:** Put a `Progress.Label` in every bar.

```tsx
/** Do example for "Name the Task" on the Progress page: put a `Progress.Label` in every bar. @module */
import { Progress, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Progress.Root value={60} {...styles.progress()}>
      <Progress.Label>Exporting 1,240 transactions</Progress.Label>
      <Progress.Value />
      <Progress.Track>
        <Progress.Indicator />
      </Progress.Track>
    </Progress.Root>
  )
}

namespace styles {
  export const progress = style({ maxWidth: '20rem !custom' })
}
```

**Don't:** Show a bar without a name for its task.

```tsx
/** Don't example for "Name the Task" on the Progress page. Don't show a bar without a name for its task. @module */
import { Progress, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Progress.Root value={60} {...styles.progress()}>
      <Progress.Value />
      <Progress.Track>
        <Progress.Indicator />
      </Progress.Track>
    </Progress.Root>
  )
}

namespace styles {
  export const progress = style({ maxWidth: '20rem !custom' })
}
```

### Move Forward Only

Use an indeterminate bar for a phase you cannot measure. A meter moves in either direction as its measurement changes.

**Do:** If a task has phases, such as upload then verification, change the label for each.

```tsx
/**
 * Do example for "Move Forward Only" on the Progress page.
 * If a task has phases, such as upload then verification, change the label for each.
 * @module
 */
import { Progress, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.steps()}>
      <Progress.Root value={90} {...styles.progress()}>
        <Progress.Label>Uploading payouts.csv</Progress.Label>
        <Progress.Value />
        <Progress.Track>
          <Progress.Indicator />
        </Progress.Track>
      </Progress.Root>
      <div {...styles.step()}>Then</div>
      <Progress.Root value={10} {...styles.progress()}>
        <Progress.Label>Verifying payments</Progress.Label>
        <Progress.Value />
        <Progress.Track>
          <Progress.Indicator />
        </Progress.Track>
      </Progress.Root>
    </div>
  )
}

namespace styles {
  export const progress = style({ maxWidth: '20rem !custom' })

  export const step = style({ color: 'content.secondary', typography: 'body.b3' })

  export const steps = style({
    display: 'flex',
    flexDirection: 'column',
    gap: '12',
    width: '100% !custom',
  })
}
```

**Don't:** Let the value decrease or restart at 0 under the same label.

```tsx
/**
 * Don't example for "Move Forward Only" on the Progress page.
 * Don't let the value decrease or restart at 0 under the same label.
 * @module
 */
import { Progress, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.steps()}>
      <Progress.Root value={90} {...styles.progress()}>
        <Progress.Label>Uploading payouts.csv</Progress.Label>
        <Progress.Value />
        <Progress.Track>
          <Progress.Indicator />
        </Progress.Track>
      </Progress.Root>
      <div {...styles.step()}>Then</div>
      <Progress.Root value={10} {...styles.progress()}>
        <Progress.Label>Uploading payouts.csv</Progress.Label>
        <Progress.Value />
        <Progress.Track>
          <Progress.Indicator />
        </Progress.Track>
      </Progress.Root>
    </div>
  )
}

namespace styles {
  export const progress = style({ maxWidth: '20rem !custom' })

  export const step = style({ color: 'content.secondary', typography: 'body.b3' })

  export const steps = style({
    display: 'flex',
    flexDirection: 'column',
    gap: '12',
    width: '100% !custom',
  })
}
```

### Report the Outcome

* **Success (positive):** Set `intent` to `positive` and change the label. Then replace the bar with the result, such as a link to the file.
* **Failure (Alert):** Don't turn the bar `negative` for a failed task. Replace it with a `negative` [Alert](/docs/components/alert) that offers Retry.

### State the Reading in Text

The `warning` and `negative` intents add color, which not every reader perceives.

**Do:** Print the amount in `Progress.Value`, such as $90.00 of a daily limit.

```tsx
/** Do example for "State the Reading in Text" on the Progress page: print the amount. @module */
import { Progress, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Progress.Root
      format={{ currency: 'USD', style: 'currency' }}
      intent="warning"
      role="meter"
      value={90}
      {...styles.progress()}
    >
      <Progress.Label>Daily limit</Progress.Label>
      <Progress.Value />
      <Progress.Track>
        <Progress.Indicator />
      </Progress.Track>
    </Progress.Root>
  )
}

namespace styles {
  export const progress = style({ maxWidth: '20rem !custom' })
}
```

**Don't:** Rely on the `warning` color alone to report a low limit.

```tsx
/** Don't example for "State the Reading in Text" on the Progress page: color alone. @module */
import { Progress, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Progress.Root
      aria-label="Daily limit"
      intent="warning"
      role="meter"
      value={90}
      {...styles.progress()}
    >
      <Progress.Track>
        <Progress.Indicator />
      </Progress.Track>
    </Progress.Root>
  )
}

namespace styles {
  export const progress = style({ maxWidth: '20rem !custom' })
}
```

## Content

* **Label:** A verb ending in -ing and its object, such as Uploading payouts.csv.
* **Units:** If a percentage hides the size of the job, count files, payments, or blocks.
* **Time estimate:** Add one only when it is reliable, and round it, such as About 2 minutes left.
* **Meter value:** State the amount and its limit, such as $90.00 of $100.00 per week.

## Accessibility

The bar is not a live region. A changed value is read only when the reader returns to it.

### Semantics

* **Progress.Root (progressbar):** Reports its range and value to assistive technology.
* **Value Text (aria-valuetext):** Defaults to a locale percentage, such as "60%". `format` and `getAriaValueText` change it.
* **Progress.Label (aria-labelledby):** Names the bar.
* **Progress.Value (aria-hidden):** Screen readers skip it and read the value text once.
* **Indeterminate Bars (value={null}):** Reports no current value. Under reduced motion, the sliding segment becomes a dimmed full bar.
* **Meters (role="meter"):** Reports a measurement, such as a limit used, with the same range, value, and label.

### Your Responsibilities

* **Describe Units (getAriaValueText):** Use it for a value with units, such as "3 of 5 files".
* **Announce Completion (SC 4.1.3):** Announce the result, such as "Upload complete", in a status message or toast.
* **Keep Label and Value Visible (4px):** The track is thin. The label and value carry the information for anyone who cannot see the fill.

## Related

[Gauge](/docs/components/gauge)

Use for a measurement in a compact ring.

[Spinner](/docs/components/spinner)

Use for a short wait of unknown length.

[Skeleton](/docs/components/skeleton)

Use for content with a known shape.

[Loading](/docs/patterns/loading)

Covers choosing a loading indicator.
