@spectrum-web-components/progress-circle

Overview

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

$3


``
yarn add @spectrum-web-components/progress-circle
`

Import the side effectful registration of 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';
`

$3

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)

`html
label="Download progress"
progress="75"
>
`

$3

#### Sizes

Progress circles come in three sizes to fit various contexts:


Small


`html demo
size="s"
label="Small progress indicator"
progress="42"
>
`


Medium


`html demo
label="Medium progress indicator"
progress="67"
>
`


Large


`html demo
size="l"
label="Large progress indicator"
progress="89"
>
`




#### Static Colors

When displaying over images or colored backgrounds, use the static-color attribute for better contrast:

`html demo



`

#### Indeterminate Progress

Use indeterminate progress when the duration cannot be calculated:

`html demo

`

$3

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

`html

label="Downloading report.pdf - 24 MB of 50 MB"
progress="48"
>


label="Connecting to server"
indeterminate
>
``