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 /><ProgressCircle aria-label="Loading…" value=50 /><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 /><ProgressCircle aria-label="Loading…" value=25 /><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
/><ProgressCircle
aria-label="Loading…"
minValue=50
maxValue=150
value=100
/><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 /><ProgressCircle aria-label="Loading…" value=50 /><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 /><ProgressCircle aria-label="Loading…" isIndeterminate /><ProgressCircle
aria-label="Loading…"
isIndeterminate
/>Accessibility#
If a visible label isn't specified, an aria-label must be provided for accessibility. If the ProgressCircle is labeled by a separate element, an aria-labelledby prop must be provided using the id of the labeling element instead.
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 | — | 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 |
id | string | — | |
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-details | string | — | Identifies the element (or elements) that provide a detailed, extended description for the object. |
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="size-300">
<ProgressCircle
aria-label="Loading…"
isIndeterminate
variant="overBackground"
/>
</View><View backgroundColor="positive" padding="size-300">
<ProgressCircle
aria-label="Loading…"
isIndeterminate
variant="overBackground"
/>
</View><View
backgroundColor="positive"
padding="size-300">
<ProgressCircle
aria-label="Loading…"
isIndeterminate
variant="overBackground"
/>
</View>Size#
<ProgressCircle
aria-label="Loading…"
marginRight="size-300"
size="S"
value=15
/>
<ProgressCircle aria-label="Loading…" marginRight="size-300" value=30 />
<ProgressCircle aria-label="Loading…" size="L" value=60 /><ProgressCircle
aria-label="Loading…"
marginRight="size-300"
size="S"
value=15
/>
<ProgressCircle
aria-label="Loading…"
marginRight="size-300"
value=30
/>
<ProgressCircle
aria-label="Loading…"
size="L"
value=60
/><ProgressCircle
aria-label="Loading…"
marginRight="size-300"
size="S"
value=15
/>
<ProgressCircle
aria-label="Loading…"
marginRight="size-300"
value=30
/>
<ProgressCircle
aria-label="Loading…"
size="L"
value=60
/>