On this page

Progress Primitive

Progress is a Starwind Runtime primitive in the static-semantic contract family.

Anatomy

Use the Astro primitive adapter to render Progress anatomy with the Runtime wiring included.

---
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>

Use the React primitive adapter when Progress state participates in React rendering.

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>
  );
}

Render the Progress data-sw-* contract yourself, then initialize createProgress.

<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.

Default element: div
Discovery hook: data-sw-progress
Role: progressbar

Props

Prop Type Default

value number | null null

Description: Controls the current Progress value.
Kind: control
Targets: -
Full type: number | null

max number 100

Description: Configures the max option for the Root part.
Kind: option
Targets: -
Full type: number

min number 0

Description: Configures the min option for the Root part.
Kind: option
Targets: -
Full type: number

format Intl.NumberFormatOptions -

Description: Configures the format option for the Root part.
Kind: option
Targets: -
Full type: Intl.NumberFormatOptions

getAriaValueText (formattedValue: string | null, value: ProgressValue) => string -

Description: Configures the get aria value text option for the Root part.
Kind: option
Targets: -
Full type: (formattedValue: string | null, value: ProgressValue) => string

locale Intl.LocalesArgument -

Description: Sets the locale used by Progress.
Kind: option
Targets: -
Full type: Intl.LocalesArgument

State

State Type Props

value ProgressValue value

Description: Tracks the current Progress value.
Initial attribute: data-value
Runtime getter: getValue
Runtime setter: setValue
State control support: 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.

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-progress - Marks the Root part so Starwind Runtime can find it.

State

Attribute Value Description

data-value - Reflects the value state on the Root part.

data-indeterminate - Reflects the indeterminate state on the Root part.

Metadata

Attribute Value Description

data-min - Reflects the min prop on the Root part.

data-max - Reflects the max prop on the Root part.

Track

The track that contains the Progress range.

Default element: div
Discovery hook: data-sw-progress-track
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-progress-track - Marks the Track part so Starwind Runtime can find it.

Indicator

Visual state indicator rendered by Progress.

Default element: div
Discovery hook: data-sw-progress-indicator
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-progress-indicator - Marks the Indicator part so Starwind Runtime can find it.

Value

Displays the current Progress value.

Default element: span
Discovery hook: data-sw-progress-value
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-progress-value - Marks the Value part so Starwind Runtime can find it.

Metadata

Attribute Value Description

data-preserve-text - Reflects the preserve text prop on the Value part.

Label

Text label associated with Progress.

Default element: span
Discovery hook: data-sw-progress-label
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-progress-label - Marks the Label part so Starwind Runtime can find it.

Runtime API

Factory: createProgress
Import: @starwind-ui/runtime/progress
Root hook: root data-sw-progress
Option props: format, getAriaValueText, locale, max, min, value

Option Lifecycles

Option	Lifecycle
format	setter-backed
getAriaValueText	setter-backed
locale	setter-backed
max	setter-backed
min	setter-backed
value	setter-backed

Runtime Setters

Method Target Description

setFormatOptions props: format, getAriaValueText, locale Updates Progress formatting options from Runtime code.

setValue props: value, max, min Updates the current Progress value from Runtime code.

Component Relationship

Progress Direct primitive

Layer Metadata

Progress Primitive uses createProgress. Styled components: Progress.

primitive Progress Primitive Progress Primitive uses createProgress. Styled components: Progress. Runtime primitive Primitive adapter Astro Primitive adapters React Primitive adapters progress Progress Static Semantic Runtime-backed markup and semantic state without overlay or form coordination. /docs/primitives/progress/ createProgress @starwind-ui/runtime/progress /docs/runtime/#create-progress root format getAriaValueText locale max min value raw-html astro react solid svelte vue HTML Astro React Solid Svelte Vue Raw HTML Render the Progress data-sw-* contract yourself, then initialize createProgress. html Use the Astro primitive adapter to render Progress anatomy with the Runtime wiring included. Use the React primitive adapter when Progress state participates in React rendering. tsx div data-sw-progress progressbar number | null Controls the current Progress value. number Configures the max option for the Root part. Configures the min option for the Root part. Intl.NumberFormatOptions Configures the format option for the Root part. (formattedValue: string | null, value: ProgressValue) => string Configures the get aria value text option for the Root part. Intl.LocalesArgument Sets the locale used by 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 Reflects the max prop on the Root part. data-indeterminate Reflects the indeterminate state on the Root part. ProgressValue getValue setValue setFormatOptions format, getAriaValueText, locale value, max, min track data-sw-progress-track Marks the Track part so Starwind Runtime can find it. indicator data-sw-progress-indicator Marks the Indicator part so Starwind Runtime can find it. span data-sw-progress-value Marks the Value part so Starwind Runtime can find it. data-preserve-text Reflects the preserve text prop on the Value part. label data-sw-progress-label Marks the Label part so Starwind Runtime can find it. Root Track Indicator Value aria-hidden Label role @starwind-ui/astro @starwind-ui/astro/progress Render static value/range markers and self-initialize; runtime owns status, ARIA value text, label linking, and indicator transform. @starwind-ui/react @starwind-ui/react/progress Create the controller once and bridge value/min/max plus formatting option changes through runtime setters. /docs/components/progress/ Direct primitive direct-primitive Styled component Progress

Progress Primitive

Anatomy

API Reference

Root

Props

State

Data Attributes

Runtime hooks

State

Metadata

Track

Data Attributes

Runtime hooks

Indicator

Data Attributes

Runtime hooks

Value

Data Attributes

Runtime hooks

Metadata

Label

Data Attributes

Runtime hooks

Runtime API

Option Lifecycles

Runtime Setters

Related Styled Components