# Progress Primitive

Progress is a Starwind Runtime primitive in the static-semantic contract family.
## 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>
```
## 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 |
| --- | --- | --- | --- | --- |
| value | `number \| null` | null | control | Controls the current Progress value. |
| 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 supports controlled state with the value prop. Runtime/HTML reads initial state from data-value and updates with setValue. Astro adapters render initial/default state, but do not expose reactive controlled-state props for this state. |
#### 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` |