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.1 |
| usage | import {ProgressCircle} from '@react-spectrum/progress' |
Example#
<ProgressCircle aria-label="Loading…" value=50 />Value#
By default ProgressCircles are controlled with the value prop representing current percentage as an integer.
In this case, the minimum and maximum 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 | — | |
slot | 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 />