sp-progress-circle

NPM 1.12.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>

Minor Changes

  • #6122 7b153b5 Thanks @rise-erpelding! - Breaking: <swc-badge> migration includes new subtle/outline styles, additional non-semantic color variants, and default behavior updates (variant="neutral" and reflected size="s" when omitted). --mod-badge-* hooks are removed, and --swc-badge-* hooks are not a strict 1:1 replacement surface for every previous override. See the badge consumer migration guide.

    Breaking: <swc-divider> migration reflects size="m" when omitted (visual medium behavior remains unchanged). --mod-divider-* hooks are removed, and the new public styling surface (--swc-divider-thickness, --swc-divider-background-color) is not a strict 1:1 replacement for prior size/static-color-specific overrides. See the divider consumer migration guide.

    Breaking: <swc-progress-circle> migration removes the indeterminate attribute (omit progress or set progress = null instead), no longer renders light DOM children as labels (use label/aria-label), and adds static-color="black" support. --mod-progress-circle-* hooks are removed, and --swc-progress-circle-* hooks are not a strict 1:1 replacement for all prior behavior. See the progress circle consumer migration guide.

    Breaking: <swc-status-light> migration removes the deprecated disabled attribute, removes the accent variant, and updates default behavior (variant="neutral" when omitted). --mod-status-light-* hooks are removed, and --swc-status-light-* hooks are not a strict 1:1 replacement for every previous override pattern. StatusLightSize is exported from core for typed usage. See the status light consumer migration guide.

Patch Changes

  • #6001 f9e0896 Thanks @cdransf! - Fixed: Added aria-valuetext attribute to <sp-progress-bar> and <sp-progress-circle> to provide human-readable percentage values for screen readers. Screen readers now announce "50 percent" instead of just "50", improving accessibility for users with vision disabilities. The attribute uses localized percentage formatting via Intl.NumberFormat and updates automatically when progress changes.

    Fixed: Added aria-valuemin and aria-valuemax attributes to <sp-progress-circle> to align with WAI-ARIA progressbar specification, matching the existing implementation in <sp-progress-bar>.

  • Updated dependencies [ba14a2b, dc6a8e8, 90c3010, f37dec6]:

    • @spectrum-web-components/base@1.12.0
    • @spectrum-web-components/reactive-controllers@1.12.0
    • @spectrum-web-components/shared@1.12.0

1.11.2

Patch Changes

  • Updated dependencies [6f5419a]:
    • @spectrum-web-components/core@0.0.4
    • @spectrum-web-components/base@1.11.2
    • @spectrum-web-components/shared@1.11.2

1.11.1

Patch Changes

  • Updated dependencies [95e1c25]:
    • @spectrum-web-components/core@0.0.3
    • @spectrum-web-components/shared@1.11.1
    • @spectrum-web-components/base@1.11.1

1.11.0

Patch Changes

  • Updated dependencies [283f0fe, 1d76b70, f8bdeec, 9cb816b]:
    • @spectrum-web-components/core@0.0.2
    • @spectrum-web-components/shared@1.11.0
    • @spectrum-web-components/base@1.11.0

1.10.0

Patch Changes

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

1.9.1

Patch Changes

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

1.9.0

Patch Changes

  • #5730 7d23140 Thanks @caseyisonit! - - Fixed: Accessibility warning logic in <sp-progress-circle> component.

    • Fixed: Updated accessibility warning logic to only apply when role="progressbar" is explicitly set
    • Fixed: Improved label validation for better accessibility compliance

    These changes ensure accessibility warnings are only shown when appropriate and improve overall accessibility compliance.

  • Updated dependencies []:

    • @spectrum-web-components/base@1.9.0
    • @spectrum-web-components/shared@1.9.0

1.8.0

Patch Changes

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

1.7.0

Patch Changes

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

1.6.0

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 label label string '' Accessible label for the progress circle.

Used to provide context about what is loading or progressing. When no accessible name is provided (no label, aria-label, or aria-labelledby), a default "Loading" label is applied.

progress progress number | null null Progress value from 0 to 100.

When null (indeterminate), the component shows a loading animation. Setting a number switches to determinate mode. Removing the progress attribute or setting this property to null returns to indeterminate. Values outside 0–100 or non-finite numbers are clamped (non-finite becomes 0).

Reflected to the progress attribute when set; the attribute is omitted when indeterminate.

size ElementSize The size of the progress circle. staticColor static-color ProgressCircleStaticColorS1 | undefined Static color variant for use on different backgrounds.

When set to 'white', the component uses white styling for images with a dark tinted background.