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'`

View guidelines

Spectrum

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#

View guidelines

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#

View guidelines

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`	`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`	`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.

'top' | 'side'

'size-0'
  | 'size-10'
  | 'size-25'
  | 'size-40'
  | 'size-50'
  | 'size-65'
  | 'size-75'
  | 'size-85'
  | 'size-100'
  | 'size-115'
  | 'size-125'
  | 'size-130'
  | 'size-150'
  | 'size-160'
  | 'size-175'
  | 'size-200'
  | 'size-225'
  | 'size-250'
  | 'size-300'
  | 'size-350'
  | 'size-400'
  | 'size-450'
  | 'size-500'
  | 'size-550'
  | 'size-600'
  | 'size-675'
  | 'size-700'
  | 'size-800'
  | 'size-900'
  | 'size-1000'
  | 'size-1200'
  | 'size-1250'
  | 'size-1600'
  | 'size-1700'
  | 'size-2000'
  | 'size-2400'
  | 'size-3000'
  | 'size-3400'
  | 'size-3600'
  | 'size-4600'
  | 'size-5000'
  | 'size-6000'
  | 'static-size-0'
  | 'static-size-10'
  | 'static-size-25'
  | 'static-size-50'
  | 'static-size-40'
  | 'static-size-65'
  | 'static-size-100'
  | 'static-size-115'
  | 'static-size-125'
  | 'static-size-150'
  | 'static-size-175'
  | 'static-size-200'
  | 'static-size-225'
  | 'static-size-250'
  | 'static-size-300'
  | 'static-size-400'
  | 'static-size-450'
  | 'static-size-500'
  | 'static-size-550'
  | 'static-size-600'
  | 'static-size-700'
  | 'static-size-800'
  | 'static-size-900'
  | 'static-size-1000'
  | 'static-size-1200'
  | 'static-size-1700'
  | 'static-size-2400'
  | 'static-size-2600'
  | 'static-size-3400'
  | 'static-size-3600'
  | 'static-size-4600'
  | 'static-size-5000'
  | 'static-size-6000'
  | 'single-line-height'
  | 'single-line-width'
  | string
  | number

Visual Options#

Over background#

View guidelines

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#

View guidelines

<Flex flexDirection="column">
  <ProgressBar label="Small" marginBottom="25px" size="S" value={70} />
  <ProgressBar label="Large" size="L" value={70} />
</Flex>