ProgressBar

A ProgressBar is a visual element used to indicate the progress of an action or process.

<cdx-progress-bar aria-label="ProgressBar example" :max="100" />

Name	Value
Props
inline
ariaLabel
value
startLabel
endLabel
max
disabled
View
Reading direction	Left to right (LTR) Right to left (RTL)

Overview

When to use ProgressBar

Use a ProgressBar when you want to provide real-time feedback on the progress of ongoing operations (such as file uploads or form submissions), or when you or when you want to show progress toward a known result. There are different types of ProgressBars, depending on your intended use.

1. Indeterminate ProgressBar (default)
   Use this variant to show that an operation is in progress when the amount of progress can’t be measured (for example, loading or processing with an unknown duration). This variation indicates that the ongoing system process will affect an entire view or area.

• Inline is available to indicate progress within other components, such as Menu or Dialog.

2. Determinate ProgressBar
   Use this variant when progress is measurable and can be represented against a known total (for example, completion percentage or progress toward a goal).

Avoid using a ProgressBar if the progress of a task is not crucial to user understanding or if the task is expected to complete quickly.

About ProgressBar

ProgressBar includes the following elements.

Progress element

Visual representation of the progress displayed as a filled bar.

Bar container

Container that holds the progress bar, showing the extent of the progress.

Label

The determinate ProgressBar can include optional labels at both sides of the bar container.

• Use a contextual label that describes what the progress represents.
• Place the counter progress at the end of the ProgressBar
• Format progress values as X / Y, where the first number represents the current progress and the second number represents the total or goal. Use a forward slash ( / ) to minimize translation needs and maintain consistency across languages.

Examples

Basic usage

<cdx-progress-bar aria-label="Indeterminate progress bar" />

Determinate with labels

Labels can be added at either end of the bar using the startLabel and endLabel props. This is useful for showing numeric indicators such as “0 / 100%” or other contextual information.

0%

25%

<cdx-progress-bar
	aria-label="Progress bar with labels"
	:value="25"
	start-label="0%"
	end-label="25%"
/>

WARNING

Due to the lack of descriptive text, a default ProgressBar requires one of the following attributes: aria-label or aria-hidden.

The aria-label attribute must be applied to the ProgressBar to ensure it is accessible to assistive technology users. An exception is an inline ProgressBar used within another component, such as the Menu component, where they are excluded from the accessibility tree by adding aria-hidden attribute.

Inline

An inline version is available for use within other components. Refer to Menu for sample usage.

<cdx-progress-bar :inline="true" />

Technical implementation

Vue usage

Props

Prop name	Description	Type	Default
value		number|null	null
max		number	100
inline	Whether this is the smaller, inline variant.	boolean	false
disabled	Whether the progress bar is disabled.	boolean	false
startLabel		string	''
endLabel		string	''

CSS-only version

Markup structure

<!-- Wrapper `<div>` element with ARIA attributes. -->
<div
  class="cdx-progress-bar"
  role="progressbar"
  aria-label="ProgressBar example"
>
  <!-- Empty inner `<div>`. -->
  <div class="cdx-progress-bar__bar" />
</div>

Inline

For an inline ProgressBar, add the cdx-progress-bar--inline class to the root <div>.

<div class="cdx-progress-bar cdx-progress-bar--inline" role="progressbar">
  <div class="cdx-progress-bar__bar" />
</div>

Disabled

For a disabled ProgressBar, add the cdx-progress-bar--disabled class to the root <div>.

<div class="cdx-progress-bar cdx-progress-bar--disabled" role="progressbar">
  <div class="cdx-progress-bar__bar" />
</div>

<div
  class="cdx-progress-bar cdx-progress-bar--inline cdx-progress-bar--disabled"
  role="progressbar"
>
  <div class="cdx-progress-bar__bar" />
</div>

Determinate

For a determinate ProgressBar, add the cdx-progress-bar--determinate class to the root <div> and set the CSS variables --cdx-progress-value and --cdx-progress-max in the style tag.

<div
  class="cdx-progress-bar cdx-progress-bar--block"
  role="progressbar"
  aria-label="Loading progress"
  style="--cdx-progress-value: 40; --cdx-progress-max: 100;"
>
  <div class="cdx-progress-bar__bar cdx-progress-bar__bar--determinate"></div>
</div>