Progress

A Progress component that visually represents the completion percentage of a task or goal.

Available from eds-core/1.9.0

Figma LibraryView in StorybookView in Playroom

Quick Start

Installation
npm install @adaptavant/eds-core
Import
import { Progress } from '@adaptavant/eds-core';

Value​

To control the filled portion of the Progress, use the value and maxValue props with numerical values.

The fill percentage is calculated as the ratio of value to maxValue, clamped between 0% and 100%.

  • If value exceeds maxValue, the Progress will display as fully filled (100%).
  • If value or maxValue is negative, the Progress will display as 0%.
<Stack className='w-full gap-4 items-stretch'>
  {/* value and maxValue positive and value is less than maxValue */}
  <Box>
    <Label className="sr-only" id="positive-progress-label">
      Progress completed
    </Label>
    <Progress value={40} maxValue={200} ariaLabelledBy="positive-progress-label" />
  </Box>

  {/* value and maxValue positive and value is higher than maxValue */}
  <Box>
    <Label className="sr-only" id="higher-progress-label">
      Progress
    </Label>
    <Progress value={400} maxValue={200} ariaLabelledBy="higher-progress-label" />
  </Box>

  {/* value is negative */}
  <Box>
    <Label className="sr-only" id="negative-progress-label">
      Progress with negative value
    </Label>
    <Progress value={-40} maxValue={100} ariaLabelledBy="negative-progress-label" />
  </Box>

  {/* maxValue is negative */}
  <Box>
    <Label className="sr-only" id="max-neg-progress-label">
      Progress with negative max value
    </Label>
    <Progress value={40} maxValue={-10} ariaLabelledBy="max-neg-progress-label" />
  </Box>
</Stack>
View in Playroom

Label​

Use ariaLabelledBy prop to properly associate to a visible or hidden label element.

Each Progress component should include a label to help users better understand the purpose of the progress indicator.

If the progress doesn't have a visible label, consider using a <Label /> component with the sr-only class to provide accessible text for screen readers.

<Stack className='w-full gap-4 items-stretch'>
	{/* Hidden Label */}
	<Box>
		<Label className="sr-only" id="progress-label">
			Progress completed
		</Label>
		<Progress value={40} maxValue={200} ariaLabelledBy="progress-label" />
	</Box>

	{/* Visible Label */}
	<Box>
		<Label id="loading-label">
			Loading
		</Label>
		<Progress value={90} maxValue={100} ariaLabelledBy="loading-label" />
	</Box>
</Stack>
View in Playroom

Adornments​

Progress component supports adornmentStart and adornmentEnd props, which allow you to render elements adjacent to the Progress.

These adornments can be interactive, such as buttons, or non-interactive, providing supplementary information like prefixes or suffixes that display the Progress percentage.

Below is an example of how you can use the adornment slots to include elements like a rating and review count alongside the Progress.

424
<Box className='w-full'>
	<Label className="sr-only" id="4-star-label">
		424, 4 star reviews out of 490 reviews
	</Label>
	<Progress
		value={424}
		maxValue={490}
		ariaLabelledBy="4-star-label"
		adornmentStart={
			<span className='flex' aria-label='4 stars out of 5' role="img">
				<ReviewStarFilledIcon className="h-3 w-3.5" tone="accentPrimary"/>
				<ReviewStarFilledIcon className="h-3 w-3.5" tone="accentPrimary"/>
				<ReviewStarFilledIcon className="h-3 w-3.5" tone="accentPrimary"/>
				<ReviewStarFilledIcon className="h-3 w-3.5" tone="accentPrimary"/>
				<ReviewStarIcon className="h-3 w-3.5" tone="accentPrimary"/>
			</span>
		}
		adornmentEnd={<Text className='text-body-14 text-primary'>424</Text>}
	/>
</Box>
View in Playroom

API Reference​

Progress

Style API​

Our design system components include style props that allow you to easily customize different parts of each component to match your design needs.

Please refer to the Style API documentation for more insights.

Progress parts​

424
<Box className="w-full">
	<Label className="sr-only" id="4-star-label">
		424, 4 star reviews out of 490 reviews
	</Label>
	<Progress
		adornmentEnd={<Text className="text-body-14 text-primary">424</Text>}
		adornmentStart={
			<span aria-label="4 stars out of 5" className="flex" role="img">
				<ReviewStarFilledIcon className="h-3 w-3.5" />
				<ReviewStarFilledIcon className="h-3 w-3.5" />
				<ReviewStarFilledIcon className="h-3 w-3.5" />
				<ReviewStarFilledIcon className="h-3 w-3.5" />
				<ReviewStarIcon className="h-3 w-3.5" />
			</span>
		}
		ariaLabelledBy="4-star-label"
		className="gap-4 p-2 rounded-8px" // targets container
		classNames={{
			adornmentStart: 'text-critical', // targets icons inside slots
			baseArea: 'bg-critical-hover', // baseArea background color can be customised
		}}
		maxValue={490}
		style={{
			backgroundColor: 'var(--background-canvas-tertiary)', // background color for container
		}}
		styles={{
			baseArea: {
				width: '200px', // controls width of progress bar
				'flex-grow': '0' // restricts baseArea taking all remaining space of container
			},
			filledArea: {
				backgroundColor: 'red', // filledArea background color can be customised
				width: '50%', // consumer passed width can't override percentage, it will always be based on value and maxValue
			},
		}}
		value={424}
	/>
</Box>
View in Playroom

Stylable Parts

Description

root

Container that wraps adornmentStart, adornmentEnd and Progress bar

baseArea

Progress bar background area.

filledArea

Progress filled area.

adornmentStart

The slot content displayed before Progress.

adornmentEnd

The slot content displayed at the end of the progress.

Usage guidelines​

Do

  1. Use the progress bar to show task completion status.
  2. Use it when tracking percentage completion.
  3. Always include a short, accessible label to explain the progress.
  4. For RTL languages, mirror the layout: right-aligned label, left-aligned value, fill progresses right to left.
  5. Placement of the percent sign may vary by locale.

Don’t

  1. Avoid unnecessary text or icons on the progress bar.
  2. Always include a clear, accessible label.
  3. Don’t use for indeterminate loading in constrained spaces; use "Loading" instead.
  4. Only use for tasks with a clear end state and measurable completion.
  5. Keep the size proportional and noticeable, but not overwhelming.
  6. Ensure color contrasts well with the background and is distinguishable.
  7. Place in a visible, accessible location.

Best practices​

Do

Always use this component horizontally.

Don’t

Do not use this component verticaly.

Do

Do place text close to the progress component.

Don’t

Do not embed text into the progress component.

Do

Do place text close to the progress bar.

Don’t

Do not place text far away from the progress bar.

Do

When styling a component with an additional token color, ensure the color is applied only to the progress indicator.

Don’t

Avoid styling the background of the progress bar indicator.