On this page

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

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

React

Use value for controlled state.

value

Astro

Use value for initial state and call setValue for later updates.

value
setValue

Runtime / HTML

Use data-value for initial state and call setValue for later updates.

data-value
setValue

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

React

Use value for controlled state.

value

Astro

Use value for initial state and call setValue for later updates.

value
setValue

Runtime / HTML

Use data-value for initial state and call setValue for later updates.

data-value
setValue

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

Changelog

View version history v1.0.0 3 releases

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.

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

Changelog

v1.0.0

v0.1.1

v0.1.0