Skip to main content

ProgressBar

Used to show users the status of loading an app, ongoing processes, saving changes/updates, and more.

github
View source code
figma
View design

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';
() => {
  return <ProgressBar percentage={25} duration={5000} label="Progress" />;
};

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.

Accessibility

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.

Important

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
DefaultA11yDescription
aria-labelledby
string | undefined
Identifies the element that provides the accessible label
Not available when the internal label is used
className
string | undefined
CSS class name to apply to each element within the component
css
CSSProperties | Partial<Record<"abyss-progress-root-container" | "abyss-progress-bar-label" | "abyss-progress-bar-style" | "abyss-progress-bar-root" | "abyss-progress-bar-popover" | ... 6 more ... | "abyss-progress-bar-cancel-button", CSSProperties>> | undefined
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 | undefined
Suffix used to create a unique ID used for automated testing
See Component Testing for more information
disableDefaultProviderProps
boolean | undefined
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 | undefined
0
The duration of the ProgressBar animation
fillColor
string | undefined
'$progress-bar.color.surface.fill'
The background color of the ProgressBar component
headingLevel
1 | 2 | 3 | 4 | 5 | 6 | undefined
3
The semantic heading level for the ProgressBar's label, so it fits correctly into the page's heading structure for screen readers.
hiddenFrom
Breakpoint | undefined
When defined, the component is hidden once the screen width reaches the specified breakpoint.
hideLabel
boolean | undefined
false
If true, visually hides the label while keeping it accessible to screen readers.
isIndeterminate
boolean | undefined
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 | undefined
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 | undefined
The label for ProgressBar component (optional when aria-labelledby is provided)
The label for ProgressBar component (required for standalone usage)
onCancel
(() => void) | undefined
false
If true, it will display a cancel button and will call the onCancel function when clicked.
percentage
number | undefined
0
The percent of the bar to be filled
popover
{ title?: string | undefined; content?: string | undefined; } | undefined
The popover content for the ProgressBar, based of the Popover component, see the documentation for more details.
progressLabel
string | number | bigint | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | Promise<...> | null | undefined
The display value in filled ProgressBar space; also announced to screen readers via aria-valuetext.
showEndpoint
boolean | undefined
false
If true, it will display a visual end point on the ProgressBar
showProgress
boolean | undefined
false
It display percentage in filled ProgressBar space
slotProps
Partial<Record<ToSlotKey<{ rootContainer: LeafSlotDef<"div", "progress-root-container">; headers: LeafSlotDef<"div", undefined>; label: LeafSlotDef<"h3", undefined>; ... 8 more ...; cancelButton: LeafSlotDef<...>; }, "progress-bar">, SlotPropsLeafValue>> | undefined
Props to pass to individual internal slots of the ProgressBar component.
See slotProps for more information
subText
string | undefined
The label subText for ProgressBar component
validation
{ type: "error" | "success"; message?: string | undefined; hideMessage?: boolean | undefined; } | undefined
undefined
If provided, the bar will change color and display a validation icon and a (optional) message, which is announced to screen readers via role="alert".
visibleFrom
Breakpoint | undefined
When defined, the component is hidden until the screen width reaches the specified breakpoint.
width
string | number | undefined
'100%'
The width of the ProgressBar component

ProgressBar Classes​

Class NameDescription
.abyss-progress-bar-cancel-buttonProgressBar cancel button element
.abyss-progress-bar-fillerProgressBar filler element
.abyss-progress-bar-headersProgressBar headers element
.abyss-progress-bar-labelProgressBar label element
.abyss-progress-bar-percent-textProgressBar percent text element
.abyss-progress-bar-popoverProgressBar popover element
.abyss-progress-bar-rootProgressBar root element
.abyss-progress-bar-styleProgressBar style element
.abyss-progress-bar-subtextProgressBar sub-text element
.abyss-progress-bar-validationProgressBar validation element
.abyss-progress-bar-validation-iconProgressBar validation icon element
.abyss-progress-root-containerProgressBar root container element

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 roleopens in a new window.

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> tagopens in a new window and WAI-ARIA role="progressbar"opens in a new window 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​

Tip

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

ProgressBar Tokens​

Token NameValue
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
Table of Contents