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