Migration Information

For teams migrating from the V1 to V2 component, please refer to the migration guide for changes to the component.

Component Guide

import { ProgressBar } from '@uhg-abyss/web/ui/ProgressBar';

label

subText

fillColor

width

duration

percentage

progressLabel

showProgress

hideLabel

showEndpoint

isIndeterminate

<ProgressBar percentage={25} duration={5000}/>

Labels

Use the label and subText props to provide information above the progress bar.

A label is required for accessibility reasons. Use the hideLabel prop to visually hide the label. See the Accessibility tab for more information.

Heading level

For better screen reader support, the label element is treated as a heading (h3). Use the headingLevel prop to manually to set the heading level of the label. The default is set to 3 which renders the heading element as an <h3>

See the Accessibility tab for more information.

Show progress and progress label

Use the showProgress prop to display the percentage number at the end of the filled progress bar space.

If showProgress is true, the label shown defaults to the percentage the progress bar is filled. Use the progressLabel prop to provide a custom label in place of this. Doing so is strongly recommended if the progress bar is used to display any value that is not a percentage.

Popover

Use the popover prop to display a popover icon next to the label. This is useful for providing additional context or information about the progress bar. The popover prop accepts an object with the following properties:

• title: The title of the popover.
• content: The content of the popover.

Visually hidden labels

Use hideLabel to visually hide the label.

Note: You are still required to provide a label to meet accessibility standards. This label will be visually hidden but still read by screen readers.

Validation

Use the validation prop to display a validation message below the progress bar. This is useful for providing feedback to the user about the progress bar's state. The validation prop accepts an object with the following properties:

• type: The type of validation message. This can be one of the following: 'success' or 'error'.
• message: The validation message to display (optional).
• hideMessage: If set to true, the message will not be displayed, but the validation icon will still be shown. This visually hides the message, but it will still be read by screen readers.

Note: The validation prop will override the showProgress prop with an icon representing the validation type.

Width

Use the width prop to set the width of the progress bar. The default width is set to 100%. This can be set to any valid CSS width value, such as 250px, 300, 75%, or 50vw.

Color

Use the fillColor prop to change the color of the progress bar fill. On this prop you can pass any six-digit hex color code, or a color token from the Color Tokens page.

Note: the background is always at 20% opacity to meet the contrast ratio of 3:1 with the background color.

Show endpoint

Use the showEndpoint prop to display a small colored tip at the end of the progress bar. This helps indicate the end of the bar.

Duration

Use the duration prop to set the time it takes in milliseconds for the fill bar to reach the set percentage. The default is set to 0.

Indeterminate

Use the isIndeterminate prop to set the progress bar to an indeterminate state. This is useful when the progress bar is used to indicate that a process is ongoing, but the exact percentage is unknown.

On cancel

Use the onCancel prop to provide a callback function that will be called when the cancel button is clicked. This is useful for providing a way for the user to cancel the progress bar.

Live progress

Use the isLive prop to set the progress bar to a live state. This is useful when the progress bar is used to indicate that a process is ongoing and updates in real time. The progress bar will fill up over time based on the updated percentage value. The use of the duration prop is optional; in this case, it determines the time it takes to fill the bar from the previous value to the new value.

Note: For the isLive prop to work, the percentage prop must be updated over time. The progress bar will not fill up automatically.

ProgressBar Props

Name	Type	Default	Required	Description
className	string	-	-	CSS class name to apply to each element within the component
css	Abyss.CSSProperties | Partial<Record<`abyss-${T}`, Abyss.CSSProperties>>	-	-	Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation See CSS Prop Styling for more information
data-testid	string	-	-	Suffix used to create a unique ID used for automated testing See Component Testing for more information
disableDefaultProviderProps	boolean	false	-	If set to true, the component will not use the DefaultPropsProvider values. If you aren’t using the DefaultPropsProvider, this prop can be ignored.
duration	number	0	-	The duration of the ProgressBar animation
fillColor	string	'$progress-bar.color.surface.fill'	-	The background color of the ProgressBar component
headingLevel	1 | 2 | 3 | 4 | 5 | 6	3	-	The offset for label heading
hideLabel	boolean	false	-	If true , it hides the label
isIndeterminate	boolean	false	-	If true, it will display an indeterminate progress bar with a looping animation This is useful for cases where the progress is unknown or not applicable.
isLive	boolean	false	-	If true, it will display a live progress bar that fills up over time. This is useful for cases where the progress is dynamic and updates in real-time.
label	string	-	-	The label for ProgressBar component (optional when aria-labelledby is provided) The label for ProgressBar component (required for standalone usage)
onCancel	() => void	false	-	If true, it will display a cancel button and will call the onCancel function when clicked.
percentage	number	0	-	The percent of the bar to be filled
popover	{ title?: string | undefined; content?: string | undefined; }	-	-	The popover content for the ProgressBar, based of the Popover component, see the documentation for more details.
progressLabel	React.ReactNode	-	-	The display value in filled ProgressBar space
showEndpoint	boolean	false	-	If true, it will display a visual end point on the ProgressBar
showProgress	boolean	false	-	It display percentage in filled ProgressBar space
subText	string	-	-	The label subText for ProgressBar component
validation	{ type: "error" | "success"; message?: string | undefined; hideMessage?: boolean | undefined; }	'undefined'	-	If provided, the bar will change color and display a validation icon and a (optional) message.
width	string | number	'100%'	-	The width of the ProgressBar component

Below are the link(s) to the relevant GitHub type files:

ProgressBar.types.ts

ProgressBar Classes

Class Name	Description
.abyss-progress-root-container	Container for the entire progress bar component
.abyss-progress-bar-headers	Container for the header section (label and subtext) of the progress bar
.abyss-progress-bar-label	Label element of the progress bar
.abyss-progress-bar-popover	Popover element for additional information on the progress bar
.abyss-progress-bar-subtext	Subtext element displayed below the progress bar label
.abyss-progress-bar-root	Root container for the progress bar track and filler
.abyss-progress-bar-style	Styled container for the progress bar track
.abyss-progress-bar-filler	Filler element indicating the current progress
.abyss-progress-bar-validation-icon	Icon that shows the validation status of the progress bar
.abyss-progress-bar-percent-text	Text element that displays the progress percentage
.abyss-progress-bar-validation	Container for validation messages related to the progress bar
.abyss-progress-bar-cancel-button	Cancel button element for the progress bar

ProgressBar is a non-focusable visual component intended to display a loading state for a page, component, or process. It is therefore important to provide labels in order to provide context. Without them, screen reader users might be unaware of the progress bar or might encounter content that has no meaning.

To learn more about role="progressbar", see the MDN ARIA docs on the progressbar role.

Labels

Making ProgressBar accessible

ARIA role="progressbar" has incomplete support by many screen readers, especially if static and unchanging (as shown below).

For best screen reader accessibility:

• Set ProgressBar.title headingLevel to nest correctly in page
  • This will help provide some context for the progressbar content
• Define ProgressBar.progressLabel for non-percentage values
  • If ProgressBar displays progress other than a percentage, it is strongly recommended to use the progressLabel prop to better describe it.
• ProgressBar.validation: Include success/error text in message
  • If using ProgressBar.validation, display a message including text indicating the state ("Completed" or "Error: ").

ProgressBar live announcements

During live updates, most screen readers (except NVDA) announce nothing. To address this, a <p aria-live="polite"> was added to announce the progress as "##%". A separate alert is triggered (immediately) upon completion.

Screen Reader Support (7/10/2025)

Though both the HTML <progress> tag and WAI-ARIA role="progressbar" have been defined for some time, screen reader for support for them is minimal to non-existent. This includes the expected aria-live behaviors to announce status updates.

Windows

• Both NVDA and JAWS
  • Support <progress> and role="progressbar"
  • Support aria-valuetext
  • Do not support aria-describedby
• NVDA
  • Announces updates to aria-valuenow as a tone that rises with percentage
  • Only supports aria-label; ignores <label> and aria-labelledby
• JAWS
  • Does not support updates to aria-valuenow
  • Ignores all but role and value
  • Does not support <label>, aria-label, or aria-labelledby

Mac

• VoiceOver

  • Does not support updates to aria-valuenow
  • Supports <progress> and role="progressbar"
  • Supports <label>, aria-label, and aria-labelledby
  • Supports aria-valuetext
  • Supports aria-describedby

Screen Reader Experience

To make this component accessible, some props are used to provide the necessary status updates. If they are not used, off-screen equivalents are used.

• progressLabel - live region
  • When visible, progressLabel text is announced on each update
    • If not visible, a progressLabel is created off-screen using ##%
  • For best screen reader experience
    • Keep content short, ideally without parentheses
      • Example: Use ##% not (##%)
    • If possible, space out progressLabel updates so they are 2-3 seconds apart
      • Rapid-fire updates lead to backlogged announcements ("1% 2% 3% 4% 5% ...")
• Validation messages - alerts
  • When using validation:
  • If validation.message is defined, its text is announced as part of an alert when displayed
  • If not, an off-screen validation.message alert is created
    • These announce
      • "Complete" for Success
      • "Error" for Error
    • As off-screen content, they also provide text alternatives for the bar and icon

Component Tokens

Note: Click on the token row to copy the token to your clipboard.

Search tokens

ProgressBar Tokens

Token Name	Value
progress-bar.color.icon.validation.success	#007000
progress-bar.color.icon.validation.error	#990000
progress-bar.color.surface.fill.default	#002677
progress-bar.color.surface.fill.success	#007000
progress-bar.color.surface.fill.error	#990000
progress-bar.color.surface.end-point	#4B4D4F
progress-bar.color.text.percentage	#4B4D4F
progress-bar.color.text.validation.success	#007000
progress-bar.color.text.validation.error	#990000
progress-bar.border-radius.all.bar	500px
progress-bar.sizing.all.icon.utility	16px
progress-bar.spacing.gap.horizontal.bar-container	8px
progress-bar.spacing.gap.vertical.root-container	8px