Skip to content

<u-progress>

<u-progress> lets you indicatate the amount of completed work, typically displayed as a progress bar.

Quick intro:

  • Use the max attribute to change the amount of total work to be done
  • Use the value attribute to change the amount of completed work
  • Remove the value attribute to change to indeterminate/unknown amount of work
  • MDN Web Docs: <progress> (HTMLProgressElement)

Example

Install

bash
npm add -S @u-elements/u-progress
bash
pnpm add -S @u-elements/u-progress
bash
yarn add -S @u-elements/u-progress
bash
bun add -S @u-elements/u-progress
html
<script type="module" src="https://unpkg.com/@u-elements/u-progress@latest/dist/u-progress.js"></script>

Attributes and props

<u-progress>

  • Attributes: all global HTML attributes such as id, class, data-
    • max can contain amount of total work to be done. Must be a valid number greater than 0. Defaults to 1.
    • value can contain amount of completed work. If present, value must be a valid number between 0 and max. If there is no value attribute, the progress bar is indeterminate; indicating work is being done, but withouth knowing of how long it will take.
  • DOM interface: HTMLProgressElement
    • HTMLProgressElement.max returns number reflecting max attribute
    • HTMLProgressElement.position returns number between 0 and 1 reflecting the calculation value / max
    • HTMLProgressElement.value returns number reflecting value value attribute
    • HTMLProgressElement.labels returns NodeListOf<HTMLLabelElement>

Styling

Styling the value bar

Currently, there are no standardized pseudo-element selectors specifically designated for <progress> elements (all existing selectors include a ::-vendor- prefix). Consequently, <u-progress> simply renders its value bar using a ::before pseudo-element:

Styling the indeterminate state

Replicating the native CSS pseudo-class :indeterminate is not possible. Instead, use the selector :not([value]), which is functionally identical, and compatible with both <u-progress> and native <progress>. Example:

css
.my-progress:not([value]) {
  /* Your indeterminate styling here */
}

Labeling

In most cases you should provide an accessible label when using <u-progress>. While you can use the standard ARIA labelling attributes aria-labelledby or aria-label, when using <u-progress> you can alternatively use the <label> element.

Accessibility

Screen reader <progress> <u-progress>
VoiceOver (Mac) + Chrome
VoiceOver (Mac) + Edge
VoiceOver (Mac) + Firefox ❌ Does not announce value, unless nested in <label>
VoiceOver (Mac) + Safari
VoiceOver (iOS) + Chrome ❌ Does not announce value
VoiceOver (iOS) + Safari ❌ Announces value, but not related max
Jaws (PC) + Chrome ❌ Announces value, but not related max
Jaws (PC) + Edge ❌ Announces value, but not related max
Jaws (PC) + Firefox
NVDA (PC) + Chrome ❌ Announces value, but not related max
NVDA (PC) + Edge ❌ Announces value, but not related max
NVDA (PC) + Firefox
Narrator (PC) + Chrome
Narrator (PC) + Edge
Narrator (PC) + Firefox
TalkBack (Android) + Chrome ❌ Announces value, but not related max
TalkBack (Android) + Firefox ❌ Announces value, but not related max
TalkBack (Android) + Samsung Internet ❌ Announces value, but not related max

Specifications

Released under the MIT License