# Progress Primitive

Progress is a Starwind Runtime primitive in the static-semantic contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render Progress anatomy with the Runtime wiring included.
```astro
---
import { Progress } from "@starwind-ui/astro/progress";
---

<Progress.Root>
  <Progress.Label>Upload progress</Progress.Label>
  <Progress.Track>
    <Progress.Indicator />
  </Progress.Track>
  <Progress.Value>Selected value</Progress.Value>
</Progress.Root>
```

### React
Use the React primitive adapter when Progress state participates in React rendering.
```tsx
import { Progress } from "@starwind-ui/react/progress";

export function Example() {
  return (
    <Progress.Root>
      <Progress.Label>Upload progress</Progress.Label>
      <Progress.Track>
        <Progress.Indicator />
      </Progress.Track>
      <Progress.Value>Selected value</Progress.Value>
    </Progress.Root>
  );
}
```

### HTML
Render the Progress data-sw-* contract yourself, then initialize createProgress.
```html
<div data-sw-progress role="progressbar">
  <span data-sw-progress-label role="presentation">Upload progress</span>
  <div data-sw-progress-track>
    <div data-sw-progress-indicator></div>
  </div>
  <span data-sw-progress-value aria-hidden="true">Selected value</span>
</div>

<script type="module">
  import { createProgress } from "@starwind-ui/runtime/progress";

  const root = document.querySelector("[data-sw-progress]");
  if (root) {
    createProgress(root);
  }
</script>
```

### Vue
Use the Vue 3.5 beta adapter to render Progress anatomy.
```vue
<script setup lang="ts">
import Progress from "@starwind-ui/vue/progress";
</script>

<template>
  <Progress.Root>
    <Progress.Label>Upload progress</Progress.Label>
    <Progress.Track>
      <Progress.Indicator />
    </Progress.Track>
    <Progress.Value>Selected value</Progress.Value>
  </Progress.Root>
</template>
```
## API Reference
### Root
The main element that owns the Progress Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-progress` |
| Role | `progressbar` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| value | `number \| null` | null | control | Controls the current Progress value. | **React:** Use value for controlled state.<br>**Astro:** Use value for initial state and call setValue for later updates.<br>**Runtime / HTML:** Use data-value for initial state and call setValue for later updates. |
| max | `number` | 100 | option | Configures the max option for the Root part. | - |
| min | `number` | 0 | option | Configures the min option for the Root part. | - |
| format | `Intl.NumberFormatOptions` | - | option | Configures the format option for the Root part. | - |
| getAriaValueText | `(formattedValue: string \| null, value: ProgressValue) => string` | - | option | Configures the get aria value text option for the Root part. | - |
| locale | `Intl.LocalesArgument` | - | option | Sets the locale used by Progress. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-progress` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-value` | state | - | Reflects the value state on the Root part. |
| `data-min` | prop | - | Reflects the min prop on the Root part. |
| `data-max` | prop | - | Reflects the max prop on the Root part. |
| `data-indeterminate` | state | - | Reflects the indeterminate state on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| value | `ProgressValue` | value | - | `data-value` | `getValue` | `setValue` | Tracks the current Progress value. | **React:** Use value for controlled state.<br>**Astro:** Use value for initial state and call setValue for later updates.<br>**Runtime / HTML:** Use data-value for initial state and call setValue for later updates. |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setFormatOptions` | props: format, getAriaValueText, locale | - | No | Updates Progress formatting options from Runtime code. |
| `setValue` | props: value, max, min | - | Yes | Updates the current Progress value from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-progress`, `data-value`, `data-min`, `data-max`, `data-indeterminate`, `role` | The progressbar needs deterministic value/range markers and progressbar semantics before the runtime computes ARIA value text. |

### Track
The track that contains the Progress range.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-progress-track` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-progress-track` | runtime | - | Marks the Track part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| track | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-progress-track` | The track is a stable runtime target for status attributes. |

### Indicator
Visual state indicator rendered by Progress.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-progress-indicator` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-progress-indicator` | runtime | - | Marks the Indicator part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| indicator | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-progress-indicator` | The indicator is positioned by the runtime after percent calculation. |

### Value
Displays the current Progress value.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-progress-value` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-progress-value` | runtime | - | Marks the Value part so Starwind Runtime can find it. |
| `data-preserve-text` | prop | - | Reflects the preserve text prop on the Value part. |
#### Refs
| Part | Public |
| --- | --- |
| value | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-progress-value`, `aria-hidden`, `data-preserve-text` | Value text is runtime-generated unless the adapter marks caller-provided text for preservation. |

### Label
Text label associated with Progress.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-progress-label` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-progress-label` | runtime | - | Marks the Label part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| label | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-progress-label`, `role` | Labels can be linked to the root by the runtime when no explicit ARIA label exists. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createProgress`](/docs/runtime/#create-progress) |
| Import | `@starwind-ui/runtime/progress` |
| Root part | root |
| Option props | format, getAriaValueText, locale, max, min, value |
| Option lifecycles | format: setter-backed, getAriaValueText: setter-backed, locale: setter-backed, max: setter-backed, min: setter-backed, value: setter-backed |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Progress](/docs/components/progress/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/progress` | `createProgress` |
| Astro Primitive | `@starwind-ui/astro/progress` | `Progress`, `ProgressRoot`, `ProgressTrack`, `ProgressIndicator`, `ProgressValue`, `ProgressLabel` |
| React Primitive | `@starwind-ui/react/progress` | `Progress`, `ProgressRoot`, `ProgressTrack`, `ProgressIndicator`, `ProgressValue`, `ProgressLabel` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Progress` |
| runtime-factory | `createProgress` |
| part | `Progress.Root` |
| part | `Progress.Track` |
| part | `Progress.Indicator` |
| part | `Progress.Value` |
| part | `Progress.Label` |
## Changelog
### v1.0.1
- Removed obsolete private-release warnings from generated Vue adapters and normalized the resulting blank line in vendored Primitive indexes.
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.1
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
### v0.1.0
- Introduced determinate and indeterminate progress state with accessible value metadata.