🚀 Big News: Socket Acquires Coana to Bring Reachability Analysis to Every Appsec Team.Learn more
Socket
DemoInstallSign in
Socket

@spectrum-web-components/progress-circle

Package Overview
Dependencies
Maintainers
7
Versions
324
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@spectrum-web-components/progress-circle

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

1.7.0
latest
Source
npm
Version published
Weekly downloads
6.5K
3.19%
Maintainers
7
Weekly downloads
 
Created
Source

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

Keywords

design-system

FAQs

Package last updated on 11 Jun 2025

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts