rc-progress

Native <progress> enhancer with a formatted value display, a restylable track/fill, and a built-in fix for the indeterminate/undefined-binding footgun.

Package

@rcarls/rc-progress

Element

<rc-progress>

Native dependency

Requires a native progress child

State model

Controlled or uncontrolled numeric value

Main events

rc-progress-complete

Related

Usage rulesrc-sliderrc-dialogTheme previews

Installation

npm

npm install @rcarls/rc-webcomponents@next

Yarn

yarn add @rcarls/rc-webcomponents@next

pnpm

pnpm add @rcarls/rc-webcomponents@next

import '@rcarls/rc-webcomponents/rc-progress/define';

Usage

Wrap a native <progress>, and name it with a <label for> or aria-label; the component renders no label of its own. Both forms work before JavaScript loads.

<label for="sync">Sync</label>
<rc-progress>
  <progress id="sync" max="100" value="40"></progress>
</rc-progress>

Live demo

Accessibility

The native <progress> keeps its progressbar role and value, so assistive technology reads the same progress before and after upgrade. The component forwards value-text to aria-valuetext and orientation="vertical" to aria-orientation. Its track, fill, and formatted value display are decorative. The bar takes no focus and has no keyboard interaction.

Determinate vs. indeterminate

Binding undefined to a live <progress>.value throws. Toggle the indeterminate attribute instead: the component removes and restores the native element's value attribute for you, so you never have to reach for that binding yourself.

Doing one job

rc-progress does not render a dialog, own any phase state, or assume anything about where it's placed. It composes cleanly with rc-dialog, a card, or an inline status row: bring your own chrome, and let rc-progress handle the bar.

Theming

The default demo mode shows the component without a package theme. Use the shared preview controls on this page to compare inherited, light, and dark color schemes or to apply the optional Material theme only inside the demo frames.

API

Properties

Property	Markup	Type	Default	Description
value	value	number	Not specified	Current progress value.
defaultValue	default-value	number | undefined	Not specified	Initial uncontrolled value. Has no effect after the first host write.
max	JS property only	number	Not specified	Maximum progress value, read directly from the native `<progress>` child's own `max` IDL property (native default `1`) rather than duplicated as a separate host attribute — the consumer already owns it by setting `max` on the slotted `<progress>` element.
indeterminate	indeterminate	boolean	false	When present, the component removes the native `<progress>`'s `value` attribute instead of asking the consumer to bind `undefined` to it — binding `undefined` to a live `<progress>.value` throws.
disabled	disabled	boolean	false	Visual-only dimming; native `<progress>` has no functional disabled state.
display	display	DisplayValue	null	Controls the live value display. - Absent (default) — no value shown. - `overlay` (or bare `display`) — centered on the bar. - `display="inline-start"` — rendered before the track, inline in the grid. - `display="inline-end"` — rendered after the track, inline in the grid.
valueText	value-text	string	''	Screen-reader value text. When set, forwarded as `aria-valuetext` on the native `<progress>` and used as the default formatted display text.
orientation	orientation	'horizontal' | 'vertical'	'horizontal'	Orientation; reflected as an attribute and forwarded to `aria-orientation`.

Events

Event	Detail type	Description
rc-progress-complete	CustomEvent	Fires once when `value` reaches `max` while not indeterminate. Does not re-fire on subsequent updates while already at max.

Slots

Name	Description
(default)	Place a `<progress>` element here.
value-display	Optional replacement for the rendered value text.

CSS Custom Properties

Property	Default	Description
--rc-progress-control-size	0.5rem	Track hit-area block size.
--rc-progress-vertical-size	12.5rem	Track length when `orientation="vertical"`.
--rc-progress-gap	var(--rc-control-gap)	Gap between track and inline value display.
--rc-progress-track-background	CanvasText	Unfilled track color.
--rc-progress-track-opacity	0.25	Unfilled track opacity.
--rc-progress-track-radius	var(--rc-control-radius)	Track border radius.
--rc-progress-fill-background	var(--rc-accent)	Filled track color.
--rc-progress-fill-transition-duration	150ms	Determinate fill transition duration.
--rc-progress-fill-transition-easing	ease-out	Determinate fill transition easing.
--rc-progress-value-color	var(--rc-text-disabled)	Value display text color.

CSS Parts

Part	Description
root	Root layout wrapper.
control	Track positioning wrapper.
track	Visual track.
fill	Filled progress segment.
value-display	Rendered value text.