sp-progress-bar

Examples API

Attributes and Properties #

Property Attribute Type Default Description
dir dir 'ltr' | 'rtl' 'ltr'
indeterminate indeterminate boolean false
label label string ''
overBackground over-background boolean false
progress progress number 0
sideLabel side-label boolean false
size size ElementSize

CSS Custom Properties #

Name Default
--spectrum-fieldlabel-m-side-padding-right var(--spectrum-global-dimension-size-150)
--spectrum-fieldlabel-m-text-color var(--spectrum-alias-label-text-color)
--spectrum-meter-m-negative-track-fill-color var(--spectrum-semantic-negative-status-color)
--spectrum-meter-m-notice-track-fill-color var(--spectrum-semantic-notice-status-color)
--spectrum-meter-m-positive-track-fill-color var(--spectrum-semantic-positive-status-color)
--spectrum-progressbar-l-border-radius var(--spectrum-global-dimension-size-50)
--spectrum-progressbar-l-height var(--spectrum-global-dimension-size-100)
--spectrum-progressbar-l-indeterminate-duration var(--spectrum-global-animation-duration-2000)
--spectrum-progressbar-l-indeterminate-fill-width var(--spectrum-global-dimension-static-percent-70)
--spectrum-progressbar-l-value-gap-y 0px
--spectrum-progressbar-l-width var(--spectrum-global-dimension-static-size-2500)
--spectrum-progressbar-m-border-radius undefined
--spectrum-progressbar-m-height var(--spectrum-global-dimension-size-75)
--spectrum-progressbar-m-indeterminate-duration var(--spectrum-global-animation-duration-2000)
--spectrum-progressbar-m-indeterminate-fill-width var(--spectrum-global-dimension-static-percent-70)
--spectrum-progressbar-m-overbackground-track-color var(--spectrum-alias-track-color-overbackground)
--spectrum-progressbar-m-overbackground-track-fill-color var(--spectrum-alias-track-fill-color-overbackground)
--spectrum-progressbar-m-track-color var(--spectrum-alias-track-color-default)
--spectrum-progressbar-m-track-fill-color var(--spectrum-semantic-informative-color-default)
--spectrum-progressbar-m-value-gap-y 0px
--spectrum-progressbar-m-width var(--spectrum-global-dimension-static-size-2400)
--spectrum-progressbar-s-border-radius undefined
--spectrum-progressbar-s-height var(--spectrum-global-dimension-size-50)
--spectrum-progressbar-s-indeterminate-duration var(--spectrum-global-animation-duration-2000)
--spectrum-progressbar-s-indeterminate-fill-width var(--spectrum-global-dimension-static-percent-70)
--spectrum-progressbar-s-value-gap-y 0px
--spectrum-progressbar-s-width var(--spectrum-global-dimension-static-size-2400)
--spectrum-progressbar-xl-border-radius undefined
--spectrum-progressbar-xl-height var(--spectrum-global-dimension-size-125)
--spectrum-progressbar-xl-indeterminate-duration var(--spectrum-global-animation-duration-2000)
--spectrum-progressbar-xl-indeterminate-fill-width var(--spectrum-global-dimension-static-percent-70)
--spectrum-progressbar-xl-value-gap-y 0px
--spectrum-progressbar-xl-width var(--spectrum-global-dimension-static-size-2800)

Description #

An <sp-progress-bar> shows the progression of a system operation such as downloading, uploading, processing, etc. in a visual way. It can represent determinate or indeterminate progress.

Usage #

See it on NPM! How big is this package in your project? Try it on webcomponents.dev

yarn add @spectrum-web-components/progress-bar

Import the side effectful registration of <sp-progress-bar> via:

import '@spectrum-web-components/progress-bar/sp-progress-bar.js';

When looking to leverage the ProgressBar base class as a type and/or for extension purposes, do so via:

import { ProgressBar } from '@spectrum-web-components/progress-bar';

Sizes #

Small
<div
style="width: var(--spectrum-global-dimension-size-3000); height: var(--spectrum-global-dimension-size-2000); display: flex; flex-direction: column; align-items: center; justify-content: space-around;"
>

<sp-progress-bar
size="s"
label="Loaded a little"
progress="22"
>
</sp-progress-bar>
</div>
Medium
<div
style="width: var(--spectrum-global-dimension-size-3000); height: var(--spectrum-global-dimension-size-2000); display: flex; flex-direction: column; align-items: center; justify-content: space-around;"
>

<sp-progress-bar
size="m"
label="Loaded a little"
progress="22"
>
</sp-progress-bar>
</div>
Large
<div
style="width: var(--spectrum-global-dimension-size-3000); height: var(--spectrum-global-dimension-size-2000); display: flex; flex-direction: column; align-items: center; justify-content: space-around;"
>

<sp-progress-bar
size="l"
label="Loaded a little"
progress="22"
>
</sp-progress-bar>
</div>
Extra Large
<div
style="width: var(--spectrum-global-dimension-size-3000); height: var(--spectrum-global-dimension-size-2000); display: flex; flex-direction: column; align-items: center; justify-content: space-around;"
>

<sp-progress-bar
size="xl"
label="Loaded a little"
progress="22"
>
</sp-progress-bar>
</div>

Variants #

Over background #

When a progress bar needs to be placed on top of a colored background, use the over background progres bar as signified by [over-background]. This progress bar uses a white opaque color no matter the background. Make sure the background offers enough contrast for the loader to be legible.

<div
style="width: var(--spectrum-global-dimension-size-3000); height: var(--spectrum-global-dimension-size-2000); display: flex; flex-direction: column; align-items: center; justify-content: space-around; background-color: var(--spectrum-alias-background-color-modal-overlay);"
>

<sp-progress-bar
label="Loaded a large amount"
progress="77"
over-background
>
</sp-progress-bar>
</div>

Indeterminate #

A progress bar can be either determinate or indeterminate as signified by [indeterminate]. By default, loaders are determinate. Use a determinate loader when progress can be calculated against a specific goal (e.g., downloading a file of a known size). Use an indeterminate loader when progress is happening but the time or effort to completion can’t be determined (e.g., attempting to reconnect to a server).

<div
style="width: var(--spectrum-global-dimension-size-3000); height: var(--spectrum-global-dimension-size-2000); display: flex; flex-direction: column; align-items: center; justify-content: space-around;"
>

<sp-progress-bar
aria-label="Loaded an unclear amount"
indeterminate
>
</sp-progress-bar>
</div>

The above sp-progress-bar also leverages the aria-label attribute in place of the label attribute in ensure that the element is labelled correctly without that label appearing visibly in the UI.

Side Label #

A progress bar can be delivered with its labeling displayed above its visual indicator or to either side. Use the boolean [side-label] attribute to define where this content should appear.

<div
style="width: var(--spectrum-global-dimension-size-3000); height: var(--spectrum-global-dimension-size-2000); display: flex; flex-direction: column; align-items: center; justify-content: space-around;"
>

<sp-progress-bar
side-label
indeterminate
label="Label Beside"
>
</sp-progress-bar>
</div>

Accessibility #

An sp-progress-bar element will register itself as a role="progressbar" element in the accessibility tree. Any value applied to the label attribute will be used both to visibly label the element and to set the aria-label attribute on the host. In cases where a visible label is not desired, be sure to include an aria-label attribute manually to ensure that the sp-progress-bar correctly fulfills its responsibilities to visitors of you site of all abilities.