Component Blueprints
Progress Ring
- HTML/CSS:Prototype
- Layout:Responsive
Customizable and configurable progress ring. Will display progress in a circular progress bar factor, and is capable of displaying iconography inside of the ring structure.
About Progress Ring#
The Progress Ring component renders a svg-based progress ring.
Content (typically iconography) can be rendered inside the progress ring. For the current supported size of this progress ring, xxs sized icons should be used.
Styling Note
If you plan to override the size properties of Progress Ring, use discrete values rather than percentages (ie. 4rem, not 40%). The inner structure of Progress Ring requires the container dimensions to remain square with an 1:1 aspect ratio, which isn't achievable with percentage values in most contexts.
Implementation Guidelines#
Defining Completeness#
The 'completeness' of the Progress Ring is indicated by the circular shape (pie slice), which is a svg shape of an arc.
The path declaration looks complex, but is actually pretty straightforward, with just a few parts that need customization.
The breakdown of the progress ring's d attribute can be broken down like so:
d="M 1 0 A 1 1 0 {isLong} 1 {arcX} {arcY} L 0 0"
- isLong: a binary flag if the arc should 'take the long path' (used for > 50% fill)
- arcX: the arc's x position, formulated by Math.cos(2 * Math.PI * fillPercent)
- arcY: the arc's y position, formulated by Math.sin(2 * Math.PI * fillPercent)
These calculations work in accordance with the defined svg viewBox, which goes from -1 to 1, on both x and y axis.
Content#
The Progress Ring is currently designed to display any icon from our icon set.
Accessibility#
.slds-progress-ring__progress is the visual indicator of progress and needs proper aria roles and settings:
role:progressbararia-valuemin:0// the smallest valid valuearia-valuemax:100// the largest valid valuearia-valuenow:{fill}// the current fill value
Proper accessibility guidelines should be followed on any icons used within this Progress Ring component.
Base#
<div class="slds-progress-ring">
<div class="slds-progress-ring__progress" role="progressbar" aria-valuemin="0" aria-valuemax="100" aria-valuenow="100" aria-label="{{Placeholder for description of progress ring}}">
<svg viewBox="-1 -1 2 2">
<circle class="slds-progress-ring__path" id="slds-progress-ring-path-5" cx="0" cy="0" r="1"></circle>Examples#
Partially Drained#
<div class="slds-progress-ring">
<div class="slds-progress-ring__progress" role="progressbar" aria-valuemin="0" aria-valuemax="100" aria-valuenow="88" aria-label="{{Placeholder for description of progress ring}}">
<svg viewBox="-1 -1 2 2">
<path class="slds-progress-ring__path" id="slds-progress-ring-path-10" d="M 1 0 A 1 1 0 1 1 0.73 -0.68 L 0 0"></path>Partially Drained with Warning Icon#
Warning
<div class="slds-progress-ring slds-progress-ring_warning">
<div class="slds-progress-ring__progress" role="progressbar" aria-valuemin="0" aria-valuemax="100" aria-valuenow="20" aria-label="{{Placeholder for description of progress ring}}">
<svg viewBox="-1 -1 2 2">
<path class="slds-progress-ring__path" id="slds-progress-ring-path-16" d="M 1 0 A 1 1 0 0 1 0.31 0.95 L 0 0"></path>Partially Filled#
<div class="slds-progress-ring">
<div class="slds-progress-ring__progress" role="progressbar" aria-valuemin="0" aria-valuemax="100" aria-valuenow="40" aria-label="{{Placeholder for description of progress ring}}">
<svg viewBox="-1 -1 2 2">
<path class="slds-progress-ring__path" id="slds-progress-ring-path-22" d="M 1 0 A 1 1 0 0 0 -0.81 -0.59 L 0 0"></path>Partially Filled with Warning Icon#
Warning
<div class="slds-progress-ring slds-progress-ring_warning">
<div class="slds-progress-ring__progress" role="progressbar" aria-valuemin="0" aria-valuemax="100" aria-valuenow="75" aria-label="{{Placeholder for description of progress ring}}">
<svg viewBox="-1 -1 2 2">
<path class="slds-progress-ring__path" id="slds-progress-ring-path-28" d="M 1 0 A 1 1 0 1 0 0.00 1.00 L 0 0"></path>With Expired Icon#
Expired
<div class="slds-progress-ring slds-progress-ring_expired">
<div class="slds-progress-ring__progress" role="progressbar" aria-valuemin="0" aria-valuemax="100" aria-valuenow="0" aria-label="{{Placeholder for description of progress ring}}">
<svg viewBox="-1 -1 2 2">
<path class="slds-progress-ring__path" id="slds-progress-ring-path-32" d="M 1 0 A 1 1 0 0 1 1.00 0.00 L 0 0"></path>Complete#
Complete
<div class="slds-progress-ring slds-progress-ring_complete">
<div class="slds-progress-ring__progress" role="progressbar" aria-valuemin="0" aria-valuemax="100" aria-valuenow="100" aria-label="{{Placeholder for description of progress ring}}">
<svg viewBox="-1 -1 2 2">
<circle class="slds-progress-ring__path" id="slds-progress-ring-path-35" cx="0" cy="0" r="1"></circle>Large Size#
<div class="slds-progress-ring slds-progress-ring_large">
<div class="slds-progress-ring__progress" role="progressbar" aria-valuemin="0" aria-valuemax="100" aria-valuenow="100" aria-label="{{Placeholder for description of progress ring}}">
<svg viewBox="-1 -1 2 2">
<circle class="slds-progress-ring__path" id="slds-progress-ring-path-38" cx="0" cy="0" r="1"></circle>Active Step#
<div class="slds-progress-ring slds-progress-ring_active-step">
<div class="slds-progress-ring__progress" role="progressbar" aria-valuemin="0" aria-valuemax="100" aria-valuenow="100" aria-label="{{Placeholder for description of progress ring}}">
<svg viewBox="-1 -1 2 2">
<circle class="slds-progress-ring__path" id="slds-progress-ring-path-41" cx="0" cy="0" r="1"></circle>Set the color of the ring to the active step color.
Theme - Warning#
<div class="slds-progress-ring slds-progress-ring_warning">
<div class="slds-progress-ring__progress" role="progressbar" aria-valuemin="0" aria-valuemax="100" aria-valuenow="100" aria-label="{{Placeholder for description of progress ring}}">
<svg viewBox="-1 -1 2 2">
<circle class="slds-progress-ring__path" id="slds-progress-ring-path-44" cx="0" cy="0" r="1"></circle>Set the color of the ring to the warning color.
Theme - Expired#
<div class="slds-progress-ring slds-progress-ring_expired">
<div class="slds-progress-ring__progress" role="progressbar" aria-valuemin="0" aria-valuemax="100" aria-valuenow="100" aria-label="{{Placeholder for description of progress ring}}">
<svg viewBox="-1 -1 2 2">
<circle class="slds-progress-ring__path" id="slds-progress-ring-path-47" cx="0" cy="0" r="1"></circle>Set the color of the ring to the expired color.
Theme - Complete#
<div class="slds-progress-ring slds-progress-ring_complete">
<div class="slds-progress-ring__progress" role="progressbar" aria-valuemin="0" aria-valuemax="100" aria-valuenow="100" aria-label="{{Placeholder for description of progress ring}}">
<svg viewBox="-1 -1 2 2">
<circle class="slds-progress-ring__path" id="slds-progress-ring-path-50" cx="0" cy="0" r="1"></circle>Set the color of the ring to the complete color and solid fill.
Overview of CSS Classes#
- Selector
- The CSS class being referred to.
- Summary
- A description of what the class does.
- Support
- Whether the class name is dev-ready (meaning it's fully vetted and tested and safe to use) or prototype (which means it's not fully vetted yet).
- Restrict
- The selector that the class name is allowed to be used on.
- Variant
- The base level pattern for a component. A variant can be extended to create another variant of that component, for example, a stateful button is a derivative of the base button.
- Modifier
- A single class that can be added to an HTML element of a component to modify its output. Typically these will be colors, sizing and positioning.
| Selector | .slds-progress-ring |
|---|---|
| Summary | Progress Ring component |
| Support | prototype |
| Restrict | div |
| Variant | True |
| Selector | .slds-progress-ring__progress |
|---|---|
| Summary | Progress indicator |
| Restrict | .slds-progress-ring div |
| Selector | .slds-progress-ring__path |
|---|---|
| Summary | |
| Restrict | .slds-progress-ring__progress path, .slds-progress-ring__progress circle |
| Selector | .slds-progress-ring__progress-head |
|---|---|
| Summary | |
| Restrict | .slds-progress-ring__progress div |
| Selector | .slds-progress-ring__content |
|---|---|
| Summary | Progress ring content area |
| Restrict | .slds-progress-ring > div |
| Selector | .slds-progress-ring_warning |
|---|---|
| Summary | Warning colors |
| Restrict | .slds-progress-ring |
| Modifier | True |
| Selector | .slds-progress-ring_expired |
|---|---|
| Summary | Expired colors |
| Restrict | .slds-progress-ring |
| Modifier | True |
| Selector | .slds-progress-ring_complete |
|---|---|
| Summary | Complete colors |
| Restrict | .slds-progress-ring |
| Modifier | True |
| Selector | .slds-progress-ring_large |
|---|---|
| Summary | Larger ring size |
| Restrict | .slds-progress-ring |
| Modifier | True |
| Selector | .slds-progress-ring_active-step |
|---|---|
| Summary | Blue progress ring |
| Restrict | .slds-progress-ring |
| Modifier | True |
Progress Ring Release Notes
2.21.0
Added
- Added aria-label attribute to the progress ring to meet accessibility requirements.
2.22.0
Fixed
- Fixed duplicate IDs by adding helper method
2.17.0
Added
- Added a shape to the progress ring to better visually indicate value by more than color alone.
2.15.1
Changed
- Completed progress rings now use
color-background-success-darkdesign token.
2.13.0
Changed
- Added sizing instructions to ensure a correct ratio.
2.12.0
Fixed
- Resolved an IE11 issue with positioning of the
.slds-progress-ring__progresselement by setting more explicit position settings.
Changed
- Set the blueprint recommendation to use a
<circle>element instead of a<path>element when the completion of the progress circle is 100%. This change resolves an IE11 rendering issue with completed rings.
2.7.0
Added
- Added an example of a progress ring that fills rather than drains, meaning the colored portion of the ring increases clockwise.