adobeOverview
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
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
progressattribute) - An optional indeterminate state (via
indeterminateattribute)
<sp-progress-circle
label="Download progress"
progress="75"
></sp-progress-circle>
Options
Sizes
Progress circles come in three sizes to fit various contexts:
<sp-tabs selected="m" auto label="Size Attribute Options">
<sp-tab value="s">Small</sp-tab>
<sp-tab-panel value="s">```html demo
<sp-progress-circle size="s" label="Small progress indicator" progress="42"
</sp-progress-circle> ```
</sp-tab-panel>
<sp-tab value="m">Medium</sp-tab>
<sp-tab-panel value="m">```html demo
<sp-progress-circle label="Medium progress indicator" progress="67"
</sp-progress-circle> ```
</sp-tab-panel>
<sp-tab value="l">Large</sp-tab>
<sp-tab-panel value="l">```html demo
<sp-progress-circle size="l" label="Large progress indicator" progress="89"
</sp-progress-circle> ```
</sp-tab-panel> </sp-tabs>
Static Colors
When displaying over images or colored backgrounds, use the static-color attribute for better contrast:
```html demo
></sp-progress-circle>
#### Indeterminate Progress
Use indeterminate progress when the duration cannot be calculated:
```html demo
<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
labelattribute value asaria-label - When determinate, adds
aria-valuenowwith the current progress - Includes
aria-valuemin="0"andaria-valuemax="100"for the progress range
- Uses the
- Status Communication:
- Screen readers announce progress updates
- Indeterminate state is properly conveyed to assistive technologies
Best Practices
- Always provide a descriptive
labelthat explains what the progress represents - Use determinate progress when possible to give users a clear sense of completion
- For determinate progress, ensure the
progressvalue 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>