ProgressCircle
ProgressCircles show the progression of a system operation such as downloading, uploading, processing, etc. in a visual way. They can represent determinate or indeterminate progress.
| install | yarn add @react-spectrum/progress |
|---|---|
| version | 3.0.0-rc.2 |
| usage | import {ProgressCircle} from '@react-spectrum/progress' |
Example#
<ProgressCircle aria-label="Loading…" value=50 />Value#
ProgressCircles are controlled with the value prop.
In this default case, the value props can be thought of as representing current percentage of progress as the minimum and maxiumum values default to 0 and 100, respectively.
<ProgressCircle aria-label="Loading…" value=25 />Alternatively, a different scale can be used by setting the minValue and maxValue.
<ProgressCircle aria-label="Loading…" minValue=50 maxValue=150 value=100 />Indeterminate#
By default, ProgressCircles are determinate. Use a determinate ProgressCircle when progress can be calculated against a specific goal.
<ProgressCircle aria-label="Loading…" value=50 />Use an indeterminate ProgressCircle when progress is happening but the time or effort to completion can’t be determined.
<ProgressCircle aria-label="Loading…" isIndeterminate />Accessibility#
ProgressCircle requires an aria-label or aria-labelledby attribute.
<div>
<ProgressCircle aria-labelledby="pc-label" isIndeterminate />
<label id="pc-label" style={display: 'block'}>Loading…</label>
</div>If using the overBackground variant, ensure the background offers enough contrast for the ProgressCircle to be legible and meets color contrast guidelines.
Internationalization#
To internationalize a ProgressCircle, a localized string should be passed to the aria-label prop (or value of the associated aria-labelledby element).
For languages that are read right to left (e.g. Hebrew and Arabic), the fill of both determinate and indeterminate ProgressCircles continues to spin clockwise.
Props#
| Name | Type | Default | Description |
size | 'S' | 'M' | 'L' | "M" | What the ProgressCircle's diameter should be. |
variant | 'overBackground' | — | The visual style of the ProgressCircle. |
isIndeterminate | boolean | "false" | Whether presentation is indeterminate when progress isn't known. |
value | number | "0" | The current value (controlled). |
minValue | number | "0" | The smallest value allowed for the input. |
maxValue | number | "100" | The largest value allowed for the input. |
UNSAFE_className | string | — | |
UNSAFE_style | CSSProperties | — |
Layout
| Name | Type | Default | Description |
flex | string | number | boolean | — | |
flexGrow | number | — | |
flexShrink | number | — | |
flexBasis | number | string | — | |
alignSelf | 'auto'
| 'normal'
| 'start'
| 'end'
| 'flex-start'
| 'flex-end'
| 'self-start'
| 'self-end'
| 'center'
| 'stretch' | — | |
justifySelf | 'auto'
| 'normal'
| 'start'
| 'end'
| 'flex-start'
| 'flex-end'
| 'self-start'
| 'self-end'
| 'center'
| 'left'
| 'right'
| 'stretch' | — | |
flexOrder | number | — | |
gridArea | string | — | |
gridColumn | string | — | |
gridRow | string | — | |
gridColumnStart | string | — | |
gridColumnEnd | string | — | |
gridRowStart | string | — | |
gridRowEnd | string | — |
Spacing
| Name | Type | Default | Description |
margin | DimensionValue | — | |
marginTop | DimensionValue | — | |
marginLeft | DimensionValue | — | |
marginRight | DimensionValue | — | |
marginBottom | DimensionValue | — | |
marginStart | DimensionValue | — | |
marginEnd | DimensionValue | — | |
marginX | DimensionValue | — | |
marginY | DimensionValue | — |
Sizing
| Name | Type | Default | Description |
width | DimensionValue | — | |
minWidth | DimensionValue | — | |
maxWidth | DimensionValue | — | |
height | DimensionValue | — | |
minHeight | DimensionValue | — | |
maxHeight | DimensionValue | — |
Positioning
| Name | Type | Default | Description |
position | 'static'
| 'relative'
| 'absolute'
| 'fixed'
| 'sticky' | — | |
top | DimensionValue | — | |
bottom | DimensionValue | — | |
left | DimensionValue | — | |
right | DimensionValue | — | |
start | DimensionValue | — | |
end | DimensionValue | — | |
zIndex | number | — | |
isHidden | boolean | — |
Accessibility
| Name | Type | Default | Description |
role | string | — | |
id | string | — | |
tabIndex | number | — | |
aria-label | string | — | Defines a string value that labels the current element. |
aria-labelledby | string | — | Identifies the element (or elements) that labels the current element. |
aria-describedby | string | — | Identifies the element (or elements) that describes the object. |
aria-controls | string | — | Identifies the element (or elements) whose contents or presence are controlled by the current element. |
aria-owns | string | — | Identifies an element (or elements) in order to define a visual, functional, or contextual parent/child relationship between DOM elements where the DOM hierarchy cannot be used to represent the relationship. |
aria-hidden | boolean | 'false' | 'true' | — | Indicates that the element is perceivable but disabled, so it is not editable or otherwise operable. |
Visual options#
Over background#
When a ProgressCircle needs to be placed on top of a colored background, use the overBackground variant.
<View backgroundColor="positive" padding="25px">
<ProgressCircle aria-label="Loading…" isIndeterminate variant="overBackground" />
</View>Size#
<ProgressCircle aria-label="Loading…" marginRight="25px" size="S" value=15 />
<ProgressCircle aria-label="Loading…" marginRight="25px" value=30 />
<ProgressCircle aria-label="Loading…" size="L" value=60 />