<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
<u-progress aria-label="Loading" value="7.5" max="10"></u-progress> <u-progress aria-label="Loading"></u-progress>
Install
npm add -S @u-elements/u-progress
pnpm add -S @u-elements/u-progress
yarn add -S @u-elements/u-progress
bun add -S @u-elements/u-progress
<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 andmax
. If there is novalue
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
returnsnumber
reflectingmax
attributeHTMLProgressElement.position
returnsnumber
between 0 and 1 reflecting the calculationvalue / max
HTMLProgressElement.value
returnsnumber
reflectingvalue
value attributeHTMLProgressElement.labels
returnsNodeListOf<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:
<u-progress aria-label="Loading" class="my-progress" value="6" max="10"></u-progress> <style> /* Styling just for example: */ .my-progress { border-radius: 9em; border: 1px solid gray; background: gainsboro; } .my-progress::before { background: tomato; } </style>
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:
.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
- DOM interface: HTMLProgressElement
- HTML Standard: The <progress> element