# ProgressBar

- Page: https://jiguang132.com/resources/astryx/docs/progress-bar
- Resource: Astryx (https://jiguang132.com/resources/astryx.md)
- All guides: https://jiguang132.com/resources/astryx/docs.md

A horizontal bar showing the completion progress of a task. Use it for operations where the duration is known, or as an animated indicator when progress can't be calculated. Supports semantic color variants, value labels, and custom formatting.

## Installation

```bash
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0
```

Requires React 19+, base CSS and a Theme provider. See [Setup](/resources/astryx/docs/getting-started).

## Progress Bar

A horizontal bar showing the completion progress of a task. Use it for operations where the duration is known, or as an animated indicator when progress can't be calculated. Supports semantic color variants, value labels, and custom formatting.

| Prop | Type | Default | Description |
|---|---|---|---|
| label * | string |  | accessible label |
| value | number | 0 | Current value (ignored when indeterminate). |
| max | number | 100 | Maximum value. |
| isLabelHidden | boolean | false | Visually hide the label (remains accessible). |
| hasValueLabel | boolean | false | Show formatted value text (ignored when indeterminate). |
| formatValueLabel | (value: number, max: number) => string |  | Custom value label formatter; defaults to a percentage string. |
| variant | 'accent' \| 'success' \| 'warning' \| 'error' \| 'neutral' | 'accent' | Semantic color variant. |
| isIndeterminate | boolean | false | Animated loading indicator for unknown progress. |
| marks | ReadonlyArray<{value: number; label: string}> |  | Fixed target marks drawn on the track at values in the same 0..max scale as value (e.g. a goal line). They stay visible whether progress is below or past them, and take their color from what they sit on: a mark inside the filled area uses the fill variant's on-color (on-accent, on-warning, on-error, and so on), a mark still out on the bare track uses the primary text color (the secondary one on a disabled bar, which dims everything it draws). Each mark requires a label: it is the mark's accessible name and the text revealed via a tooltip on hover/focus. Ignored when indeterminate. |
| isDisabled | boolean | false | Visually disabled state: grays out the fill and text. Use for canceled or inactive operations. |
| xstyle | StyleXStyles |  | StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}. |

### Usage guidance

- Use a determinate bar when the total amount of work is known, and indeterminate when it's not.
- Choose a color variant that matches the context: accent for general progress, success for completion, warning or error for alerts.
- Always provide a label, even if hidden; screen readers need it to announce what's loading.
- Avoid: Place icons or labels inside the bar; compose them alongside it using layout components.
- Avoid: Use a progress bar for instant actions; it's meant for operations that take noticeable time.
- Avoid: Use multiple progress bars stacked together for the same operation; use one bar with a value label instead.

### Theming API

```json
{
  "targets": [
    {
      "className": "astryx-progress-bar",
      "visualProps": [
        "variant"
      ]
    },
    {
      "className": "astryx-progress-bar-fill",
      "visualProps": [
        "variant"
      ]
    },
    {
      "className": "astryx-progress-bar-track"
    },
    {
      "className": "astryx-progress-bar-mark",
      "visualProps": [
        "variant",
        "placement"
      ]
    }
  ],
  "vars": [
    {
      "name": "--_progressbar-mark-width",
      "description": "Target mark tick width",
      "default": "2px",
      "private": true
    },
    {
      "name": "--_progressbar-mark-height",
      "description": "Target mark tick height",
      "default": "8px",
      "private": true
    }
  ],
  "derived": [
    {
      "property": "width",
      "vars": [
        "--_progressbar-mark-width"
      ],
      "replaces": true
    },
    {
      "property": "height",
      "vars": [
        "--_progressbar-mark-height"
      ],
      "replaces": true
    }
  ]
}
```

### Anatomy

- **Progress bar**: Container arranging the label row and progress track.
- **Label**: Text naming the operation, optionally hidden visually while remaining accessible.
- **Value text**: Formatted determinate value shown beside the label when requested.
- **Track**: Remaining-progress rail that carries the progressbar semantics.
- **Fill**: Painted segment showing completed progress or indeterminate movement.
- **Mark**: Labeled target tick positioned on a determinate track.


## Examples

- Progress Bar: A progress bar filled to 60%.
- ProgressBar — Custom Format: Progress bar with a custom value label showing disk usage in GB.
- ProgressBar — Indeterminate: Indeterminate progress bar for operations with unknown duration.
- ProgressBar — Semantic Variants: All semantic color variants stacked vertically.
- ProgressBar — With Value Label: Progress bar with its current percentage displayed.

---

Index of all JGuang resources: https://jiguang132.com/llms.txt