Skip to content

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).

Full width

Indeterminate ​

Use indeterminate when the duration of an operation is unknown. The bar animates continuously.

Full width

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".

Full width

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.

Full width

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.

Full width

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.

Full width

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".

Full width

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 ​

Full width

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.

Full width

Indeterminate ​

Full width

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.

Full width

Colors ​

Use semantic color to reinforce state: color="success" when complete, color="error" on failure.

Full width

Sizes ​

Three sizes that affect bar height (linear) or ring diameter (circular). Default circular diameter is 6rem.

Full width
Full width

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.

Full width

Dynamic Updates ​

Update value programmatically to reflect real progress.

js
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 ​

AttributeTypeDefaultDescription
valuenumber0Current progress value; clamped to [min, max]. Ignored when indeterminate.
minnumber0Range start; drives the fill ratio and aria-valuemin.
maxnumber100Range end; drives the fill ratio and aria-valuemax.
indeterminatebooleanfalseShow 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/ATheme color for the fill
size'sm' | 'md' | 'lg'N/ABar height (linear) or ring diameter (circular/gauge)
labelstringN/AVisible 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.
titlestringN/ALinear: header text above the bar; moves label to the header row when combined. Circular/gauge: smaller text below the label inside the ring.
show-valuebooleanfalseShow the rounded percentage wherever the label renders (end label, header row, inside the ring, floating chip). An explicit label/floating-label wins.
floating-labelstringN/AText 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.
segmentsnumber0Split 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-textstringN/AHuman-readable value for screen readers (e.g. "Step 2 of 5"). Overrides the raw aria-valuenow.

CSS Custom Properties ​

PropertyDescriptionDefault
--progress-heightLinear bar height overrideSize-dependent
--progress-track-bgTrack (unfilled background) color--color-contrast-200
--progress-fillFill bar / stroke colorTheme-dependent
--progress-radiusLinear bar border radiusvar(--rounded-full)
--progress-circle-sizeCircular/gauge ring diameter6rem (size-dependent)
--progress-stroke-widthCircular/gauge ring thicknessSize-dependent
--progress-floating-label-colorFloating chip text colorTheme contrast ink
--progress-circular-label-sizeFont size of the label inside the ring--text-xl (size-dependent)
--progress-circular-title-sizeFont size of the title inside the ring--text-xs (size-dependent)
--progress-label-gapGap between header/bar row and between bar and trailing label0.25rem
--progress-segment-gapGap between blocks when segments is setvar(--size-1)
--progress-title-colorTitle text colorcurrentColor
--progress-label-colorLabel text colorcurrentColor

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.