@spectrum-web-components/progress-bar

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

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: 240px; height: 160px; 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: 240px; height: 160px; 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: 240px; height: 160px; 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: 240px; height: 160px; 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: 240px; height: 160px; display: flex; flex-direction: column; align-items: center; justify-content: space-around; background-color: var(--spectrum-transparent-black-400);"
>
    <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: 240px; height: 160px; 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: 240px; height: 160px; 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.

Changelog

1.7.0 (2025-06-11)

Minor Changes

sp-overlay: Fixed : Overlays (like pickers and action menus) were incorrectly closing when scrolling occurred within components. The fix ensures the handleScroll method in OverlayStack only responds to document/body scrolling events and ignores component-level scrolling events, which was the original intention.

sp-card: Fixed: On mobile Chrome (both Android and iOS), scrolling on sp-card components would inadvertently trigger click events. This was caused by the timing-based click detection (200ms threshold) in the pointer event handling, which could misinterpret quick scrolls as clicks. This issue did not affect Safari on mobile devices.

sp-action-button: - Fixed : Action buttons with href attributes now properly detects modifier keys and skips the proxy click, allowing only native browser behavior to proceed.

Patch Changes

sp-styles: Remove unnecessary system theme references to reduce complexity for components that don't need the additional mapping layer.

sp-card: - Fixed: sp-card component relies on sp-popover for certain toggle interactive behaviors, but this dependency was missing from its dependency tree.

sp-menu: Fixes: Icons in menu stories weren't properly responding to theme changes when used in functional story components. Switching to class-based LitElement components ensures proper component lifecycle hooks and shadow DOM context for icon initialization and theme integration.

sp-tabs: Added @spectrum-web-components/action-button as a dependency for Tabs as its used in the direction button.

sp-split-view: Added @spectrum-web-components/shared dependency in splitview since it uses ranDomId from the shared package

sp-textfield: Replace deprecated word-break: break-word with overflow-wrap: break-word to align with modern CSS standards and improve cross-browser compatibility. This property was deprecated in Chrome 44 (July 2015) in favor of the standardized overflow-wrap property.