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" />

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

<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 use aria-label

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

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

2. Use a <label> tag linked with the ProgressBar, 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 is a convenient wrapper for several components: ProgressBarContainer, Progress, and ProgressOutput. Core props are forwarded to ProgressBarContainer, and other props are forwarded to Progress.

Using this API, you can create an accessible Progress Bar without a visible text label, for example.

ReactVanilla

<ProgressBarContainer>
  <Progress value={45} aria-label="Uploading file" />
</ProgressBarContainer>

<ProgressBarContainer>
  <Progress value={45} aria-label="Uploading file" />
</ProgressBarContainer>

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

Best practices

Use when uploading or downloading large files or a longer system operation.

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.

prop	type	required	description	default
aria-label	`string`	false	Defines a string value that labels the current element. Provides a localized accessible label for the progress bar. e.g. "File upload progress" @see aria-labelledby.	null
aria-labelledby	`string`	false	Identifies the element (or elements) that labels the current element. ID of an element whose text content labels the progress bar. The referenced element's text should be localized. e.g. id of element with text "File upload progress" @see aria-describedby.	null

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.

prop	type	required	description	default
aria-label	`string`	false	Defines a string value that labels the current element. Provides a localized accessible label for the progress bar. e.g. "File upload progress" @see aria-labelledby.	null
aria-labelledby	`string`	false	Identifies the element (or elements) that labels the current element. ID of an element whose text content labels the progress bar. The referenced element's text should be localized. e.g. id of element with text "File upload progress" @see aria-describedby.	null