Component
ki-progress
A token-styled, non-interactive progress indicator for known or unknown duration work — uploads, downloads, installations, multi-step processing.
<ki-progress value="64" label="Uploading report.pdf"></ki-progress>Examples
Section titled “Examples”Determinate and indeterminate
Section titled “Determinate and indeterminate”Use value/max when the completed fraction is known; use indeterminate
when work is ongoing but cannot be measured — including loading-indicator
use cases:
<ki-progress value="30" max="120" label="Processing 30 of 120 records"></ki-progress><ki-progress indeterminate label="Connecting"></ki-progress>Shapes
Section titled “Shapes”linear fits page flows and lists; circular fits compact or centered
placements:
<ki-progress shape="circular" value="64" label="Uploading report.pdf"></ki-progress><ki-progress shape="circular" indeterminate label="Loading results"></ki-progress>API reference
Section titled “API reference”When to use: communicate advancement of an ongoing task such as upload, download, installation or multi-step processing. Use value/max when the completed fraction is known; use indeterminate when work is ongoing but its duration cannot be measured, including loading-indicator use cases. Choose linear in page flows and lists, and circular in compact or centered placements. Always set label to what is progressing.
When not to use: static measurements within a known range such as disk usage or scores (gauge/meter), step-by-step wizard navigation (stepper), skeleton placeholders while content loads, or operations that finish in under about one second.
Properties & attributes
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
indeterminate | indeterminate | boolean | false | Unknown-duration mode. When set, no completed fraction or current value is exposed. Its motion is declared only when reduced motion is not requested. When to use: show ongoing work whose duration or total cannot be measured. When NOT to use: do not use for known fractions; use value and max. |
label | label | string | undefined | – | Accessible name applied to the internal progressbar. Always set this to what is progressing, such as "Uploading report.pdf". Without it the element renders but exposes no accessible name. When NOT to use: do not use a generic label such as "Loading" when the task can be named more specifically. |
max | max | number | 100 | Total amount. Non-finite, zero or negative values normalize to 100 for presentation and ARIA. When to use: set when a determinate task's total is not 100. When NOT to use: omit for conventional percentage-style progress. |
shape | shape | "circular" | "linear" | 'linear' | Structural presentation. Use linear in page flows and lists; use circular in compact or centered placements. Unknown values render linear. When NOT to use: do not use shape to encode semantic status or task intent. |
value | value | number | 0 | Completed amount. Presentation and ARIA clamp this value to 0..max; malformed values fall back to 0. Ignored while indeterminate is set. When to use: set with max for determinate task advancement. When NOT to use: do not set a fabricated value for unknown-duration work; set indeterminate instead. |
CSS parts
| Part | Description |
|---|---|
indicator | The advancing fill or arc: indicator ink and indeterminate animation. |
track | The full channel or ring: track ink and radius/stroke geometry. |
CSS custom properties
The public styling contract of ki-progress: reassign these tokens at :root or on a subtree — never override internals.
| Token | Description |
|---|---|
--ki-motion-duration-fast | Fast interaction transition duration. |
--ki-motion-duration-medium-2 | M3 md.sys.motion.duration.medium2 (300ms). onmars: MarsUI moderate step (240ms). |
--ki-motion-easing-out | Decelerating interaction transition easing curve. |
--ki-motion-easing-standard | Standard interaction transition easing curve. |
--ki-progress-circular-size | dimension used by the progress component for circular size. |
--ki-progress-circular-track-width | dimension used by the progress component for circular track width. |
--ki-progress-indeterminate-duration | duration used by the progress component for progress indeterminate duration. |
--ki-progress-indicator-color | MarsUI fills components with the med-em (500) tone of the ramp (marsui-design-dna.md §1; specs/002-ki-button/design-extraction.md §§2.1-2.4 delta 500-vs-high-em): progress indicator uses surface.primary-med-em. |
--ki-progress-linear-radius | dimension used by the progress component for linear radius. |
--ki-progress-linear-thickness | dimension used by the progress component for linear thickness. |
--ki-progress-track-color | color used by the progress component for track color. |
--ki-typography-family-body | semantic font family for typography family body. |
Accessibility
Section titled “Accessibility”Always set label to what is progressing (“Uploading report.pdf”, never
just “Progress”). For static measurements within a known range (disk usage,
scores) a gauge/meter is the right pattern, and step-by-step wizard
navigation belongs to a future stepper — not this component.