@spectrum-web-components/progress-circle

Overview

An <sp-progress-circle> shows the progression of a system operation such as downloading, uploading, processing, etc. in a visual way. It can represent both determinate and indeterminate progress, helping users understand the status of ongoing operations.

Usage

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

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

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

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

import { ProgressCircle } from '@spectrum-web-components/progress-circle';

Anatomy

A progress circle consists of several key parts:

• A label (via slot="label")
• A progress value (via progress attribute)
• An optional indeterminate state (via indeterminate attribute)

<sp-progress-circle
    label="Download progress"
    progress="75"
></sp-progress-circle>

Options

Sizes

Progress circles come in three sizes to fit various contexts:

Small

<sp-progress-circle
    size="s"
    label="Small progress indicator"
    progress="42"
></sp-progress-circle>

Medium

<sp-progress-circle
    label="Medium progress indicator"
    progress="67"
></sp-progress-circle>

Large

<sp-progress-circle
    size="l"
    label="Large progress indicator"
    progress="89"
></sp-progress-circle>

Static Colors

When displaying over images or colored backgrounds, use the static-color attribute for better contrast:

<div style="background-color: rgb(15, 15, 15); padding: 20px;">
    <sp-progress-circle
        label="Progress on dark background"
        progress="50"
        static-color="white"
    ></sp-progress-circle>
</div>

Indeterminate Progress

Use indeterminate progress when the duration cannot be calculated:

<sp-progress-circle label="Loading content" indeterminate></sp-progress-circle>

Accessibility

The <sp-progress-circle> element implements several accessibility features:

• ARIA Role: Automatically sets role="progressbar" for proper semantic meaning
• Labeling:
  • Uses the label attribute value as aria-label
  • When determinate, adds aria-valuenow with the current progress
  • Includes aria-valuemin="0" and aria-valuemax="100" for the progress range
• Status Communication:
  • Screen readers announce progress updates
  • Indeterminate state is properly conveyed to assistive technologies

Best Practices

• Always provide a descriptive label that explains what the progress represents
• Use determinate progress when possible to give users a clear sense of completion
• For determinate progress, ensure the progress value accurately reflects the actual progress
• Consider using size="l" for primary loading states to improve visibility
• Ensure sufficient color contrast when using static-color="white"

<!-- Example with good accessibility -->
<sp-progress-circle
    label="Downloading report.pdf - 24 MB of 50 MB"
    progress="48"
></sp-progress-circle>

<!-- For unknown duration operations -->
<sp-progress-circle
    label="Connecting to server"
    indeterminate
></sp-progress-circle>

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.