Progress
A progress indicator for conveying operation completion. Supports a classic linear bar, a circular ring, a half-circle gauge, and a vertical bar, all with determinate (known value) and indeterminate (unknown duration) modes.
For loading placeholders before progress can be determined, see Skeleton.
Linear Bar
Determinate
Show a known value between 0 and max (default: 100).
<ore-progress value="0"></ore-progress>
<ore-progress value="25"></ore-progress>
<ore-progress value="60"></ore-progress>
<ore-progress value="100"></ore-progress>Indeterminate
Use indeterminate when the duration of an operation is unknown. The bar animates continuously.
<ore-progress indeterminate></ore-progress> <ore-progress indeterminate color="primary"></ore-progress>Label
The label attribute renders visible text and doubles as the accessible aria-label.
Linear:
- Without
title: rendered at the end of the bar (trailing inline). - With
title: moved into the header row above the bar.
Circular: renders as large, bold text centered inside the ring.
Always set label (or title) to a meaningful description like "Uploading file: 45%" so screen readers have a useful accessible name. When neither is set, aria-label falls back to "Progress".
<ore-progress value="40" label="40%"></ore-progress>
<ore-progress value="70" color="primary" label="70 / 100 tasks"></ore-progress>
<ore-progress value="100" color="success" label="Complete"></ore-progress>Title
The title attribute provides contextual text.
Linear: displayed as a header row above the bar. When both title and label are set, the label moves into the header row right-aligned next to the title.
Circular: displayed as smaller text below the label inside the ring.
Use title + label together to build a self-contained progress widget: the title names the operation and the label shows the current value.
<!-- Title only -->
<ore-progress value="60" title="Uploading files…"></ore-progress>
<!-- Title + label in header row -->
<ore-progress value="60" color="primary" title="Uploading files…" label="60%"></ore-progress>Show Value
The show-value attribute renders the rounded percentage wherever the label would appear: the end label, the header row, centered inside the ring, or the floating chip. An explicit label (or floating-label for the chip) still wins, so show-value is the zero-formatting default and label the override.
<ore-progress show-value value="40"></ore-progress>
<ore-progress show-value title="Uploading files…" value="62"></ore-progress>
<ore-progress show-value type="circular" color="primary" value="75"></ore-progress>Floating Label
The floating-label attribute renders a chip above the fill endpoint, centered on the current progress position. The chip tracks the fill value as it changes. It is automatically hidden when indeterminate is set. With show-value and no floating-label, the chip shows the percentage. Set floating-label-position="bottom" to place the chip below the track instead. The chip's text uses the theme's designed contrast ink for the fill color in both themes; override it with --progress-floating-label-color if you repaint --progress-fill.
<ore-progress value="40" floating-label="40%"></ore-progress>
<ore-progress value="65" color="primary" floating-label="65 pts"></ore-progress>
<ore-progress value="80" color="success" show-value floating-label-position="bottom"></ore-progress>Segments
Set segments to split the linear bar into discrete blocks. Blocks up to value / max are filled, which reads as a token track (stages, steps, struggle) rather than a percentage. Ignored when indeterminate or type="vertical".
<ore-progress value="2" max="6" segments="6" label="2 / 6" color="error"></ore-progress>
<ore-progress value="3" max="5" segments="5" title="Onboarding" label="Step 3 of 5" value-text="Step 3 of 5"></ore-progress>Circular
Set type="circular" to render a circular progress ring. The default diameter is 6rem (sm: 4rem, lg: 9rem): large enough to display content inside. Use circular for dashboard metrics, profile completions, or storage indicators where the ring itself communicates the proportion. For circular, combine label (value like "75%") with title (context like "Storage") for a self-contained widget.
Determinate
<ore-progress type="circular" value="25"></ore-progress>
<ore-progress type="circular" value="50" color="primary"></ore-progress>
<ore-progress type="circular" value="75" color="success"></ore-progress>
<ore-progress type="circular" value="100" color="info"></ore-progress>Label and Title inside the ring
Use label for the primary value text centered inside the ring, and title for a smaller descriptor below it.
<!-- Label only -->
<ore-progress type="circular" value="75" color="primary" label="75%"></ore-progress>
<!-- Label + title -->
<ore-progress type="circular" value="512" max="1024" color="warning" label="50%" title="Storage"></ore-progress>
<!-- lg size -->
<ore-progress type="circular" size="lg" value="3" max="10" color="success" label="3 / 10" title="Steps"></ore-progress>Indeterminate
<ore-progress type="circular" indeterminate></ore-progress>
<ore-progress type="circular" indeterminate color="primary"></ore-progress>
<ore-progress type="circular" indeterminate color="warning"></ore-progress>Gauge
Set type="gauge" for a half-circle ring that sweeps from 9 o'clock over the top to 3 o'clock — the classic dashboard gauge. Everything from the circular variant applies: label/title inside the ring, show-value, colors, sizes, and indeterminate mode. The layout box stays square like the circular variant; the arc occupies its top half.
<ore-progress type="gauge" value="25" label="25%" title="CPU"></ore-progress>
<ore-progress type="gauge" color="primary" show-value value="60"></ore-progress>
<ore-progress type="gauge" color="error" show-value value="90"></ore-progress>Colors
Use semantic color to reinforce state: color="success" when complete, color="error" on failure.
<ore-progress value="60"></ore-progress>
<ore-progress value="60" color="primary"></ore-progress>
<ore-progress value="60" color="secondary"></ore-progress>
<ore-progress value="60" color="info"></ore-progress>
<ore-progress value="60" color="success"></ore-progress>
<ore-progress value="60" color="warning"></ore-progress>
<ore-progress value="60" color="error"></ore-progress>Sizes
Three sizes that affect bar height (linear) or ring diameter (circular). Default circular diameter is 6rem.
<ore-progress size="sm" value="60"></ore-progress>
<ore-progress size="md" value="60"></ore-progress>
<ore-progress size="lg" value="60"></ore-progress><!-- sm: 4rem -->
<ore-progress type="circular" size="sm" value="60" label="60%"></ore-progress>
<!-- md: 6rem (default) -->
<ore-progress type="circular" size="md" value="60" label="60%"></ore-progress>
<!-- lg: 9rem -->
<ore-progress type="circular" size="lg" value="60" label="60%"></ore-progress>Custom Range
The default range is 0 to max (100). Set min and max to track any range (e.g. bytes already transferred, temperatures). Values outside the range clamp, and aria-valuemin/aria-valuemax reflect the bounds.
<ore-progress value="3" max="10" color="primary" title="Step 3 of 10" label="3 / 10"></ore-progress>
<ore-progress value="512" min="256" max="1024" color="primary" label="512 MB of 1 GB"></ore-progress>
<ore-progress type="circular" value="750" max="1000" color="success" label="750 MB of 1 GB"></ore-progress>Dynamic Updates
Update value programmatically to reflect real progress.
const bar = document.querySelector('ore-progress');
let progress = 0;
const interval = setInterval(() => {
progress += 5;
bar.setAttribute('value', String(progress));
if (progress >= 100) {
clearInterval(interval);
}
}, 200);API Reference
Attributes
| Attribute | Type | Default | Description |
|---|---|---|---|
value | number | 0 | Current progress value; clamped to [min, max]. Ignored when indeterminate. |
min | number | 0 | Range start; drives the fill ratio and aria-valuemin. |
max | number | 100 | Range end; drives the fill ratio and aria-valuemax. |
indeterminate | boolean | false | Show infinite animation when duration is unknown |
type | 'linear' | 'circular' | 'gauge' | 'vertical' | 'linear' | Indicator style; 'gauge' is the half-circle ring |
color | 'primary' | 'secondary' | 'info' | 'success' | 'warning' | 'error' | N/A | Theme color for the fill |
size | 'sm' | 'md' | 'lg' | N/A | Bar height (linear) or ring diameter (circular/gauge) |
label | string | N/A | Visible text label and accessible name. Linear without title: rendered at bar end. Linear with title: moved to the header row. Circular/gauge: large text centered inside the ring. Falls back to title, then "Progress" for aria-label. |
title | string | N/A | Linear: header text above the bar; moves label to the header row when combined. Circular/gauge: smaller text below the label inside the ring. |
show-value | boolean | false | Show the rounded percentage wherever the label renders (end label, header row, inside the ring, floating chip). An explicit label/floating-label wins. |
floating-label | string | N/A | Text for the floating chip above the fill endpoint (linear only). Hidden when indeterminate. |
floating-label-position | 'top' | 'bottom' | 'top' | Side of the track the floating chip sits on. |
segments | number | 0 | Split the linear bar into this many discrete blocks; blocks up to the (value − min) / (max − min) ratio are filled. Ignored when indeterminate or vertical. |
value-text | string | N/A | Human-readable value for screen readers (e.g. "Step 2 of 5"). Overrides the raw aria-valuenow. |
CSS Custom Properties
| Property | Description | Default |
|---|---|---|
--progress-height | Linear bar height override | Size-dependent |
--progress-track-bg | Track (unfilled background) color | --color-contrast-200 |
--progress-fill | Fill bar / stroke color | Theme-dependent |
--progress-radius | Linear bar border radius | var(--rounded-full) |
--progress-circle-size | Circular/gauge ring diameter | 6rem (size-dependent) |
--progress-stroke-width | Circular/gauge ring thickness | Size-dependent |
--progress-floating-label-color | Floating chip text color | Theme contrast ink |
--progress-circular-label-size | Font size of the label inside the ring | --text-xl (size-dependent) |
--progress-circular-title-size | Font size of the title inside the ring | --text-xs (size-dependent) |
--progress-label-gap | Gap between header/bar row and between bar and trailing label | 0.25rem |
--progress-segment-gap | Gap between blocks when segments is set | var(--size-1) |
--progress-title-color | Title text color | currentColor |
--progress-label-color | Label text color | currentColor |
Accessibility
The progress component follows WAI-ARIA best practices. role="progressbar" is applied to the track element. aria-valuenow reflects the current value clamped to [min, max] and is omitted when indeterminate. aria-valuemin and aria-valuemax reflect min and max. aria-label resolves in priority order: label → title → "Progress". Use value-text via the value-text attribute to provide a human-readable override for screen readers (e.g. "Step 3 of 10"), which sets aria-valuetext. The inner .circular-inner overlay (label + title) is positioned with position: absolute; inset: 0 so the SVG ring renders independently; text never spins even when indeterminate is active. Animations respect prefers-reduced-motion: the sliding/spinning animation is disabled and a static representation is shown.