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

  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>

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/base@1.6.0
    • @spectrum-web-components/shared@1.6.0

1.5.0

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/base@1.5.0
    • @spectrum-web-components/shared@1.5.0

1.4.0

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/base@1.4.0
    • @spectrum-web-components/shared@1.4.0

1.3.0

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/base@1.3.0
    • @spectrum-web-components/shared@1.3.0

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

1.2.0 (2025-02-27)

Note: Version bump only for package @spectrum-web-components/progress-circle

1.1.2 (2025-02-12)

Note: Version bump only for package @spectrum-web-components/progress-circle

1.1.1 (2025-01-29)

Note: Version bump only for package @spectrum-web-components/progress-circle

1.1.0 (2025-01-29)

Bug Fixes

  • lock prerelease versions for Spectrum CSS (#5014) (8aa7734)

1.0.1 (2024-11-11)

Note: Version bump only for package @spectrum-web-components/progress-circle

1.0.0 (2024-10-31)

BREAKING CHANGES

  • remove progress-circle overBackground property (#4750)

0.49.0 (2024-10-15)

Features

  • add static-color to replace static (#4808) (43cf086)

0.48.1 (2024-10-01)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.48.0 (2024-09-17)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.47.2 (2024-09-03)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.47.1 (2024-08-27)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.47.0 (2024-08-20)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.46.0 (2024-08-08)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.45.0 (2024-07-30)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.44.0 (2024-07-15)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.43.0 (2024-06-11)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.42.5 (2024-05-24)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.42.4 (2024-05-14)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.42.3 (2024-05-01)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.42.2 (2024-04-03)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.42.1 (2024-04-02)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.42.0 (2024-03-19)

Bug Fixes

  • progress-circle: remove aria-label only when set by label and changed label is empty (cdd181a)

Features

  • asset: use core tokens (99e76f4)

0.41.2 (2024-03-05)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.41.1 (2024-02-22)

Bug Fixes

  • progress-circle: ensure size can be applied to non-"size" attribute bearing elements (2bc1065)

0.41.0 (2024-02-13)

Features

  • icon: use core tokens (a11ef6b)

0.40.5 (2024-02-05)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.40.4 (2024-01-29)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.40.3 (2024-01-11)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.40.2 (2023-12-18)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.40.1 (2023-12-05)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.40.0 (2023-11-16)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.39.4 (2023-11-02)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.39.3 (2023-10-18)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.39.2 (2023-10-13)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.39.1 (2023-10-06)

Bug Fixes

  • progress-circle,toast,tooltip: ensure complete dependency graph (#3701) (a5dfada)

0.39.0 (2023-09-25)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.38.0 (2023-09-05)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.37.0 (2023-08-18)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.36.0 (2023-08-18)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.35.0 (2023-07-31)

Bug Fixes

  • meter, progress-bar, progress-circle: use innerText when label is not provided (#3483) (59358c7)

0.34.0 (2023-07-11)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.33.2 (2023-06-14)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.33.0 (2023-06-08)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.32.0 (2023-06-01)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.31.0 (2023-05-17)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.30.0 (2023-05-03)

Bug Fixes

  • update to latest spectrum-css packages (a5ca19f)

Features

  • adopt DNA@7 base Spectrum CSS (e08cafd)
  • delivery dev mode messages in various packages (62370a1)
  • include all Dev Mode files in side effects (f70817c)
  • progress-circle: replace circle-loader with progress-circle (a852140)
  • progress-circle: use core tokens (587ac63)
  • shared pkg versions, devmode define warning, registry-conflicts docs (6e49565)
  • use latest exports specification (a7ecf4b)

0.7.9 (2023-04-24)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.7.8 (2023-04-05)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.7.7 (2023-03-22)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.7.6 (2023-02-08)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.7.5 (2023-01-23)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.7.4 (2023-01-09)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.7.3 (2022-12-08)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.7.2 (2022-11-21)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.7.1 (2022-11-14)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.7.0 (2022-10-28)

Features

  • progress-circle: use core tokens (587ac63)

0.6.0 (2022-08-09)

Features

  • include all Dev Mode files in side effects (f70817c)

0.5.0 (2022-08-04)

Features

  • delivery dev mode messages in various packages (62370a1)

0.4.11 (2022-07-18)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.4.10 (2022-06-29)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.4.9 (2022-06-07)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.4.8 (2022-05-27)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.4.7 (2022-05-12)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.4.6 (2022-04-21)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.4.5 (2022-03-08)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.4.4 (2022-03-04)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.4.3 (2022-02-22)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.4.2 (2022-01-26)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.4.1 (2021-12-13)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.4.0 (2021-11-08)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.3.1 (2021-11-08)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.3.0 (2021-11-02)

Features

  • adopt DNA@7 base Spectrum CSS (e08cafd)

0.2.8 (2021-09-20)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.2.7 (2021-07-22)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.2.6 (2021-06-16)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.2.5 (2021-05-12)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.2.4 (2021-04-09)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.2.3 (2021-03-29)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.2.2 (2021-03-22)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.2.1 (2021-03-05)

Note: Version bump only for package @spectrum-web-components/progress-circle

0.2.0 (2021-03-04)

Features

  • use latest exports specification (a7ecf4b)

0.1.1 (2021-02-11)

Bug Fixes

  • update to latest spectrum-css packages (a5ca19f)

0.1.0 (2021-02-02)

Features

  • progress-circle: replace circle-loader with progress-circle (a852140)

Attributes and Properties

Property Attribute Type Default Description indeterminate indeterminate boolean false label label string '' progress progress number 0 staticColor static-color 'white' | undefined