Progress Bar

Displays the percentage of completion of a system operation.

styleKeys: progressBarscriptKeys: progressBar

UsageGuidelinesAPI

Progress Bar is a determinate indicator that informs the user of the percentage of completion of a system operation.

Usage

ReactVanilla

<>
  <ProgressBar value={45} aria-label="Uploading file" />{' '}
  {/* localised `aria-label` */}
</>

<>
  <ProgressBar value={45} aria-label="Uploading file" />{' '}
  {/* localised `aria-label` */}
</>

<div class="swan-progress-bar-container">
  <progress
    value="45"
    max="100"
    aria-label="Uploading file"
    class="swan-progress"
  ></progress>
  <output class="swan-progress-label">45%</output>
</div>

<div class="swan-progress-bar-container">
  <progress
    value="45"
    max="100"
    aria-label="Uploading file"
    class="swan-progress"
  ></progress>
  <output class="swan-progress-label">45%</output>
</div>

Accessibility

The component leverages semantic HTML elements like <progress> and <output> to provide inherent accessibility features. However, a consumer must provide an appropriate localized label, ensuring that the progress bar component is usable by all individuals, including those relying on assistive technologies. It can be provided in any of the below-mentioned ways:

1. If there’s no visible text to describe the progress bar, you can add an aria-label directly to the ProgressBar / Progress (in case using composed components)

<ProgressBar aria-label="uploading file" value={45} />

<ProgressBar aria-label="uploading file" value={45} />

2. Use a <label> tag linked with the ProgressBar / Progress (in case using composed components) or any other element like span or a div to describe the progress bar via aria-labelledby.

<>
  <label htmlFor="sample-progress-bar">uploading file</label>
  <ProgressBar id="sample-progress-bar" value={45} />

  {/* Link by using `aria-labelledby` in case of any other element */}
  <span id="progress-bar-description">uploading file</span>
  <ProgressBar
    id="sample-progress-bar"
    aria-labelledby="progress-bar-description"
    value={45}
  />
</>

<>
  <label htmlFor="sample-progress-bar">uploading file</label>
  <ProgressBar id="sample-progress-bar" value={45} />

  {/* Link by using `aria-labelledby` in case of any other element */}
  <span id="progress-bar-description">uploading file</span>
  <ProgressBar
    id="sample-progress-bar"
    aria-labelledby="progress-bar-description"
    value={45}
  />
</>

Convenience Component

ProgressBar

ProgressBar has no props of its own

All props are forwarded to the element specified in the as prop (default: <progress/>)

The React ProgressBar is a convenience component made of these sub-components:

<ProgressBarContainer className={className}>
  <Progress {...otherProps} value={value} />
  <ProgressOutput>{value}%</ProgressOutput>
</ProgressBarContainer>

<ProgressBarContainer className={className}>
  <Progress {...otherProps} value={value} />
  <ProgressOutput>{value}%</ProgressOutput>
</ProgressBarContainer>

Note that if you use this API, ProgressBarContainer uses the className prop instead of Progress.

Best practices

Use when uploading or downloading large files or a longer system operation.
When customizing the Progress component via themes, you can add a border or drop shadow around the bar, but be aware that some browsers (including Chrome and Safari) can be inconsistent about the width, making it appear thicker on some sides.

Implementation

In vanilla JS, if you need to change the value of the progress bar, you will need to use the function setProgressValue() on the <progress> DOM node, e.g. setProgressValue(myProgressBarNode, 23); This function will update both the progress bar and the numeric label.

Props

ProgressBarContainer

This component is implemented using the <div /> as the root element. You can utilize the native attributes supported by <div /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.

See core props for additional props that can be applied to this component.

ProgressBar

This component is implemented using the <div /> as the root element. You can utilize the native attributes supported by <div /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.

See core props for additional props that can be applied to this component.

ProgressOutput

This component is implemented using the <output /> as the root element. You can utilize the native attributes supported by <output /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.

See core props for additional props that can be applied to this component.

Progress

This component is implemented using the <progress /> as the root element. You can utilize the native attributes supported by <progress /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.

See core props for additional props that can be applied to this component.