sp-progress-circle

NPM 1.6.0

View Storybook

Try it on Stackblitz
Overview API Changelog

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

See it on NPM! How big is this package in your project? Try it on Stackblitz

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 Medium 
<sp-progress-circle
    label="Medium progress indicator"
    progress="67"
></sp-progress-circle>
 Large

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>