ProgressBar
ProgressBars show the progression of a system operation: downloading, uploading, processing, etc., in a visual way. They can represent either determinate or indeterminate progress.
| install | yarn add @react-spectrum/progress |
|---|---|
| version | 3.0.0-rc.1 |
| usage | import {ProgressBar} from '@react-spectrum/progress' |
Example#
<ProgressBar label="Loading…" value=50 />Value#
ProgressBars 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.
<ProgressBar label="Loading…" value=25 />Alternatively, a different scale can be used by setting the minValue and maxValue.
<ProgressBar label="Loading…" minValue=50 maxValue=150 value=100 />Values are formatted as a percentage by default, but can be modified by using the formatOptions for different formats.
formatOptions is compatible with the option parameter of Intl.NumberFormat and is applied to the current locale.
<ProgressBar label="Loading…" formatOptions={style: 'currency' currency: 'JPY'} value=60 />Indeterminate#
By default, ProgressBars are determinate. Use a determinate ProgressBar when progress can be calculated against a specific goal.
<ProgressBar label="Loading…" value=50 />Use an indeterminate ProgressBar when the wait time or effort to completion can not be determined.
<ProgressBar label="Loading…" isIndeterminate />Accessibility#
Depending on the visualization being used (i.e. depending on the showValueLabel prop), a label, aria-label, or aria-labelledby attribute is required.
<div>
<ProgressBar aria-labelledby="pc-label" showValueLabel=false value=45 />
<label id="pc-label" style={display: 'block'}>Loading…</label>
</div>If using the over background variant, ensure the background offers enough contrast for the ProgressBar to be legible and meets color contrast guidelines.
Internationalization#
To internationalize a ProgressBar, a localized string should be passed to the label prop, 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 layout is mirrored for both determinate and indeterminate options.
Labels#
Labels and value labels are shown by default on top, but they can also be moved to the side or hidden as needed.
<Flex flexDirection="column" maxWidth="250px">
<ProgressBar label="Loading…" marginBottom="25px" value=30 />
<ProgressBar label="Loading…" marginBottom="25px" labelPosition="side" value=30 />
<ProgressBar label="Loading…" showValueLabel=false value=30 />
</Flex>Value labels by default show the percentage of progress in a determinate ProgressBar. These can be customized using the following props.
showValueLabel: Hides the value label
formatOptions: Allows you to customize the format of the percentage
valueLabel: Allows you to customize the value label to any string.
<Flex flexDirection="column" maxWidth="250px">
<ProgressBar label="Loading…" marginBottom="25px" showValueLabel=false value=30 />
<ProgressBar label="Loading…" marginBottom="25px" valueLabel="30 of 60 dogs" value=30 />
<ProgressBar label="Loading…" formatOptions={style: 'percent' minimumFractionDigits: 2} value=30.123 />
</Flex>Props#
| Name | Type | Default | Description |
variant | 'overBackground' | — | |
size | 'S' | 'L' | — | |
labelPosition | | — | |
label | ReactNode | — | |
showValueLabel | boolean | — | |
formatOptions | | — | |
valueLabel | ReactNode | — | |
value | number | — | |
minValue | number | — | |
maxValue | number | — | |
UNSAFE_className | string | — | |
UNSAFE_style | CSSProperties | — | |
isIndeterminate | boolean | — |
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 | | — | |
marginTop | | — | |
marginLeft | | — | |
marginRight | | — | |
marginBottom | | — | |
marginStart | | — | |
marginEnd | | — | |
marginX | | — | |
marginY | | — |
Sizing
| Name | Type | Default | Description |
width | | — | |
minWidth | | — | |
maxWidth | | — | |
height | | — | |
minHeight | | — | |
maxHeight | | — |
Positioning
| Name | Type | Default | Description |
position | 'static'
| 'relative'
| 'absolute'
| 'fixed'
| 'sticky' | — | |
top | | — | |
bottom | | — | |
left | | — | |
right | | — | |
start | | — | |
end | | — | |
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 ProgressBar needs to be placed on top of a colored background, use the overBackground variant.
<View backgroundColor="positive" padding="25px">
<ProgressBar label="Loading…" variant="overBackground" value=5 />
</View>Size#
<Flex flexDirection="column">
<ProgressBar label="Small" marginBottom="25px" size="S" value=70 />
<ProgressBar label="Large" size="L" value=70 />
</Flex>