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:

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

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

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

1. ARIA Role: Automatically sets role="progressbar" for proper semantic meaning
2. 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
3. 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>