<c-progress-bar>
A horizontal progress bar that fills a track to a known completion percentage, with an optional details line showing the value and a label.
Usage
Bind the completion percentage to value (0–100; out-of-range values are clamped for the bar). By default a details line renders below the progress track — the percentage plus whatever the label prop supplies (e.g. "57 % Uploading files"). Hide it with hide-details, or place it beside the track with single-line.
For work of unknown duration the indeterminate prop turns the bar into a looping sweep and hides the details line.
When to use
- For progress whose completion percentage is known — uploads, batch jobs, multi-step processing — or, with
indeterminate, for an unknown-duration wait that should still read as a full-width bar. - When space is tight or each item in a set needs its own compact indicator,
c-progress-circleis the circular determinate counterpart. - For a plain inline activity indicator use
c-spinner; to cover a whole region while it loads, usec-loader.
Details line
The details line shows the raw value even when the bar clamps it, and a negative value renders the line in the error role — a hook for signalling a failed transfer while keeping the bar itself empty.
Accessibility
The progress track is the element with role="progressbar", exposing aria-valuenow (0 to 100) while determinate; in indeterminate mode no value is exposed. The host mirrors aria-busy (true while indeterminate) and a title tooltip with the current percentage. The progress bar is named by label, or, where a visible label would be redundant (a table cell), by an aria-label on the element. Name every progress bar.
Customization
Restyle via the parts:
::part(track): the progress track the bar grows along. Itsbackground-coloris the track's colour, itsheightthe bar's thickness plus the frame, and itspaddingthe frame around the bar.::part(bar): the bar showing the value, also the indeterminate sweep. Itsbackground-coloris the bar's colour.::part(root): the wrapper around the track and the details line.::part(details): the percentage and label line.
By default the bar paints the primary role on a muted track. In a forced-colors mode (Windows High Contrast) the bar paints the system highlight colour whatever its ::part() colour.
c-progress-bar.quota::part(track) {
background-color: var(--c-surface-sunken);
height: 12px;
padding: 2px;
}
c-progress-bar.quota::part(bar) {
background-color: var(--c-warning);
}
Examples
<template>
<div>
<c-progress-bar label="Uploading files" value="72" />
</div>
</template>
<template>
<div>
<c-progress-bar label="Processing data" indeterminate />
</div>
</template>
API reference
<c-progress-bar>
A horizontal progress bar that fills a track to a known completion percentage, with an optional details line showing the value and a label.
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
hideDetails | hide-details | boolean | false | Hides the details line (the percentage and `label`); `label` still names the progress bar. |
indeterminate | indeterminate | boolean | false | Turns the bar into a looping sweep for work of unknown duration, hiding the details line and exposing no value. |
label | label | string | '' | What is progressing: shown after the percentage, and the progress bar's accessible name. |
singleLine | single-line | boolean | false | Places the details line beside the progress track instead of below it. |
value | value | number | 0 | Completion percentage, 0 to 100. The bar clamps a value outside that range; the details line shows it as given, a negative one in the error colour. |
CSS parts
Style from outside with c-progress-bar::part(name) — parts are the library's only styling customization API.
| Part | Description |
|---|---|
root | The outer flex wrapper around the progress track and the details line |
track | The progress track: the ground the bar grows along, carrying the progressbar role. Its padding is the frame around the bar |
bar | The bar showing the value: the fill, or the looping sweep while indeterminate |
details | The percentage and label text line |