x-progress

A linear progress bar web component with variant colors, optional value label, indeterminate animation, and a completion event.

Tag

<x-progress value="60" max="100"></x-progress>

Observed Attributes

Attribute	Type	Default	Values
value	number	0	Numeric string, clamped to [0, max]
max	number	100	Numeric string > 0; falls back to 100
variant	enum	default	default success warning danger
size	enum	md	sm md lg
label	string	—	Visible label rendered above the track
show-value	boolean	absent	Shows computed percentage text
indeterminate	boolean	absent	Animated shimmer; ignores value

Attributes that belong together. This component acts at the moment an attribute is written: it sends x-progress-complete. It uses the other attributes as they are at that moment. When you change several attributes that belong together, write them in one step, so the component sees one state. See "The hold of a render" in UTILITIES.md.

Properties

Property	Type	Reflects attribute
value	string	value
max	string	max
variant	string	variant
size	string	size
label	string	label
indeterminate	boolean	indeterminate
showValue	boolean	show-value

Events

Event	Bubbles	Detail	When
x-progress-complete	yes	{ value: number, max: number }	Once when value >= max; resets when value < max

Slots

None. Label text is provided via the label attribute.

CSS Custom Properties

Property	Default	Description
--x-progress-height	4px / 8px / 12px (by size)	Track height
--x-progress-track-color	var(--x-color-border,rgba(0,0,0,0.10))	Background of the track
--x-progress-fill-color	var(--x-color-primary,#3b82f6)	Fill color
--x-progress-border-radius	var(--x-radius-full,9999px)	Radius for track and fill
--x-progress-label-color	var(--x-color-text-muted,rgba(0,0,0,0.60))	Color of the label text
--x-progress-value-color	var(--x-color-text-muted,rgba(0,0,0,0.50))	Color of the percentage value text

Accessibility

• role="progressbar" is set on the host element.
• aria-valuenow, aria-valuemin="0", aria-valuemax reflect the current numeric state.
• aria-valuetext shows e.g. "75%" or "Loading…" when indeterminate.
• aria-label mirrors the label attribute.
• aria-busy="true" is set when indeterminate is present; removed otherwise.
• When indeterminate, aria-valuenow and aria-valuemax are removed. No maximum of an earlier state is left on the host.

Shadow DOM Structure

:host [role=progressbar aria-valuenow aria-valuemin aria-valuemax aria-valuetext]
  <style>
  <div part="base" data-variant data-size data-indeterminate>
    <div part="header">           ← hidden when neither label nor show-value
      <span part="label-text">   ← textContent = label attribute
      <span part="value-text">   ← textContent = "75%" when show-value
    <div part="track">
      <div part="fill">          ← width driven by inline style %

Usage Examples

Basic

<x-progress value="40"></x-progress>

With label and value display

<x-progress value="75" label="Upload progress" show-value></x-progress>

Variants

<x-progress value="100" variant="success"></x-progress>
<x-progress value="60"  variant="warning"></x-progress>
<x-progress value="30"  variant="danger"></x-progress>

Sizes

<x-progress value="50" size="sm"></x-progress>
<x-progress value="50" size="md"></x-progress>
<x-progress value="50" size="lg"></x-progress>

Indeterminate

<x-progress indeterminate label="Loading…"></x-progress>

Listening for completion

document.querySelector('x-progress').addEventListener('x-progress-complete', e => {
  console.log('Done!', e.detail); // { value: 100, max: 100 }
});

Custom theme

x-progress {
  --x-progress-fill-color: #8b5cf6;
  --x-progress-track-color: #ede9fe;
  --x-progress-height: 10px;
}