<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

NPM

npm add -S @u-elements/u-progress

PNPM

pnpm add -S @u-elements/u-progress

Yarn

yarn add @u-elements/u-progress

Bun

bun add -S @u-elements/u-progress

CDN

<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:

.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.

Server side rendering

You can server side render <u-progress> by using Declarative Shadow DOM. Styling and markup needed is exported as UHTMLProgressShadowRoot. Example:

import { UHTMLProgressShadowRoot } from '@u-elements/u-progress';

const renderToStaticMarkup = (value?: number, max?: number) =>
 `<u-progress
   ${value ? ` value="${value}"` : ''}
   ${max ? ` max="${max}"` : ''}
 >
   ${UHTMLProgressShadowRoot}
 </u-progress>`

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

Changelog

• 0.0.6: Enable declarative shadow root support and export UHTMLProgressShadowRoot for easier server side rendering