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
Installation
- npm
- Yarn
npm install @rcarls/rc-progress
yarn add @rcarls/rc-progress
import '@rcarls/rc-progress/define';
Live demo
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`. |
Methods
No public methods are documented in the custom elements manifest.
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-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. |