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

• Uses role="progressbar" with proper ARIA attributes
• aria-valuenow, aria-valuemin, aria-valuemax for determinate
• aria-label for accessible name when label is not visible
• aria-labelledby links to visible label when show-value is true
• aria-busy indicates indeterminate state
• Warns in console when label attribute is missing
• High contrast mode support
• Respects prefers-reduced-motion

When to Use:

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

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="Almost full"></hy-progress>
<hy-progress value="30" variant="danger" label="Low storage"></hy-progress>

Custom max value

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

Custom styling

<hy-progress
  value="70"
  label="Progress"
  style="--hy-progress-indicator-color: deeppink;"
></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.
showValue	show-value	boolean	false	Whether to visually display the percentage/value.
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

Property	Description
--hy-progress-gap	Gap between progress bar and label
--hy-progress-gap-label	Gap between label elements
--hy-progress-radius	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-track-color	Background color of the track
--hy-progress-enter-duration	Transition duration for the determinate value-change animation
--hy-progress-enter-easing	Transition easing for the determinate value-change animation
--hy-progress-pulse-duration	Indeterminate pulse animation duration
--hy-progress-pulse-easing	Indeterminate pulse animation easing
--hy-progress-ring-size	Ring diameter (overrides all sizes at once)
--hy-progress-ring-thickness	Ring stroke width (overrides all sizes at once)