HyProgress

Usage examples on this page are written for Lit / plain HTML (<hy-progress>). The same component ships as HyProgress in @whitespaceux/harmony-react (native React 19), with typed wrappers for Angular, Solid, Svelte, and Vue. The API reference below applies to all frameworks.

A linear progress bar that displays the completion status of a task.

Progress bars show either determinate progress (known percentage) or indeterminate progress (unknown duration). For indeterminate circular loading, use the Spinner component instead.

Key Features:

• Determinate mode with percentage display
• Indeterminate mode with animated indicator
• Three size variants (small, medium, large)
• Four status variants (default, success, warning, danger)
• Customizable via CSS custom properties
• SSR compatible

Accessibility: built in

• The host is the progressbar (ElementInternals), with aria-valuenow, aria-valuemin, aria-valuemax and aria-valuetext for determinate progress
• Named by label, or by aria-label / aria-labelledby on the host — both work natively, since the role sits on the host itself
• aria-busy indicates indeterminate state
• Warns in console when label attribute is missing
• High contrast mode support
• Respects prefers-reduced-motion

Accessibility: your part

• Always set label to the work under way, such as "Uploading photos", even when no visible label shows.
• When variant turns success, warning or danger, say the outcome in text next to the bar. The color alone is not announced.
• Announce completion and failure, for example with a hy-alert or a hy-toast, so people who cannot see the bar learn the result.

When to Use:

• File uploads/downloads with known progress
• Multi-step processes
• Form submission progress
• Any operation with measurable completion

Progress or meter?

Progress moves toward completion (an upload, a set of steps). A reading within a known range — storage used, a quota, battery, password strength — is hy-meter, which derives its color from the value.

When to use

• A task whose progress can be measured: an upload, an import, a setup.
• A long task whose length is unknown, with indeterminate.

Do

• Show the percentage, with show-value, when the task takes long.
• Name the task in its label.

When not to use

• Unknown duration operations (use Spinner or indeterminate mode)
• Page-level loading (consider Skeleton)
• Very short operations (no indicator needed)

Examples

Basic determinate progress

<hy-progress value="75" label="Upload progress"></hy-progress>

With visible percentage

<hy-progress value="50" label="Loading" show-value></hy-progress>

Indeterminate mode

<hy-progress indeterminate label="Processing"></hy-progress>

Different sizes

<hy-progress value="60" size="small" label="Progress"></hy-progress>
<hy-progress value="60" size="medium" label="Progress"></hy-progress>
<hy-progress value="60" size="large" label="Progress"></hy-progress>

Status variants

<hy-progress value="100" variant="success" label="Complete"></hy-progress>
<hy-progress value="80" variant="warning" label="Stalled"></hy-progress>
<hy-progress value="30" variant="danger" label="Upload failed"></hy-progress>

Custom max value

<hy-progress value="3" max="5" label="Step 3 of 5" show-value></hy-progress>

Custom styling

<style>
  .upload {
    --hy-progress-bar-color: var(--hy-background-brand-solid-rest);
  }
</style>
<hy-progress class="upload" value="70" label="Progress"></hy-progress>

Circular ring

<hy-progress shape="ring" value="70" label="Upload progress" show-value></hy-progress>

API

Properties

Property	Attribute	Type	Default	Description
value	value	number	0	Current progress value.
max	max	number	100	Maximum value for the progress bar.
size	size	'small' | 'medium' | 'large'	'medium'	Size of the progress bar.
variant	variant	'default' | 'success' | 'warning' | 'danger'	'default'	Visual variant indicating status.
indeterminate	indeterminate	boolean	false	Whether to show indeterminate (unknown progress) animation.
label	label	string	''	Accessible label describing the progress.
indeterminateLabel	indeterminate-label	string	'In progress'	Announced value (aria-valuetext) of an indeterminate progress bar. Use for internationalization.
valueLabel	value-label	string	'{value} of {max}'	Announced value (aria-valuetext) when max is not 100, a template: {value} and {max}, both in the locale's digits. At max 100 the locale's percent is announced instead. Use for internationalization.
showValue	show-value	boolean	false	Whether to visually display the percentage/value.
locale	locale	string | undefined	—	BCP-47 locale for the value's digits and percent sign, shown and announced. Unset, the nearest lang (across shadow roots), else the browser's language.
shape	shape	'linear' | 'ring'	'linear'	Geometry of the progress indicator.

CSS Parts

Part	Description
base	The component's base wrapper element
track	The background track element (linear shape)
indicator	The filled progress indicator (linear shape)
ring	The circular SVG wrapper (ring shape)
label-container	Container for label and value text
label	The label text element
value	The value/percentage text element (centered for the ring shape)

CSS Custom Properties

The documented hooks. Every override hook the component reads — one per token it paints — is listed in @whitespaceux/harmony/theme-api.json, and @whitespaceux/harmony/component-bindings.json (the Harmony MCP get-bindings tool) says which part and state each one paints.

Property	Default	Description
--hy-progress-gap-layout-2xs	var(--hy-gap-layout-2xs)	Gap between progress bar and label
--hy-progress-gap-layout-xs	var(--hy-gap-layout-xs)	Gap between label elements
--hy-progress-radius-pill-md	var(--hy-radius-pill-md)	Border radius of the track and indicator
--hy-progress-track-height-sm	—	Track height for small size
--hy-progress-track-height-md	—	Track height for medium size
--hy-progress-track-height-lg	—	Track height for large size
--hy-progress-bar-color	—	Override color for the progress indicator bar
--hy-progress-background-surface-medium	var(--hy-background-surface-medium)	Background color of the track
--hy-progress-motion-transition-enter-duration	var(--hy-motion-transition-enter-duration)	Transition duration for the determinate value-change animation
--hy-progress-motion-transition-enter-easing	var(--hy-motion-transition-enter-easing)	Transition easing for the determinate value-change animation
--hy-progress-motion-loop-pulse-duration	var(--hy-motion-loop-pulse-duration)	Indeterminate pulse animation duration
--hy-progress-motion-loop-pulse-easing	var(--hy-motion-loop-pulse-easing)	Indeterminate pulse animation easing
--hy-progress-control-height-md	var(--hy-control-height-md)	Ring diameter (overrides all sizes at once)
--hy-progress-control-height-sm	var(--hy-control-height-sm)	Ring diameter (overrides all sizes at once)
--hy-progress-control-height-lg	var(--hy-control-height-lg)	Ring diameter (overrides all sizes at once)
--hy-progress-ring-thickness-progress-track-height-sm	var(--hy-progress-track-height-sm)	Ring stroke width (overrides all sizes at once)
--hy-progress-ring-thickness-progress-track-height-md	var(--hy-progress-track-height-md)	Ring stroke width (overrides all sizes at once)