progress-bar

Progress Bar

View on MongoDB.design

Description

The ProgressBar component supports two types:

• Indeterminate — shows an infinite looping animation to indicate ongoing activity without specifying exact progress. Useful when the duration or total work is unknown.
• Determinate — shows measurable progress toward a known maximum. When using a determinate progress bar, specify whether you're using it as a:
  • Meter — a snapshot of current value, often with a health/status indication (e.g., disk space used).
  • Progress bar — a dynamic bar that fills as a task progresses toward completion (e.g., file upload).

Installation

PNPM

pnpm add @leafygreen-ui/progress-bar

Yarn

yarn add @leafygreen-ui/progress-bar

NPM

npm install @leafygreen-ui/progress-bar

Example

Determinate Bar With Progress Role (Default)

import ProgressBar from '@leafygreen-ui/progress-bar';

const [uploaded, setUploaded] = useState(0);
const [paused, setPaused] = useState(false);
const total = 100;

<ProgressBar
  variant="success"
  label="File Upload"
  size="small"
  description="Your data is uploading!"
  disabled={paused}
  formatValue={(value: number, maxValue: number) =>
    `${value}/${maxValue} files`
  }
  showIcon
  value={uploaded}
  maxValue={total}
/>;

Determinate Bar With Meter Role

import ProgressBar from '@leafygreen-ui/progress-bar';

const [used, setUsed] = useState(96);
const totalSpaceAvailable = 128;

<ProgressBar
  role="meter"
  variant="warning"
  label="Disk Space Used"
  formatValue={(value: number, maxValue: number) =>
    `${value}/${maxValue} GB used`
  }
  value={used}
  maxValue={totalSpaceAvailable}
/>;

Indeterminate Bar

import ProgressBar from '@leafygreen-ui/progress-bar';

<ProgressBar
  isIndeterminate
  label="Loading report"
  description="This might take a few seconds..."
/>;

Properties

Prop	Type	Default	Applicable To	Description
size?	'small' | 'default' | 'large'		all	Optional size (thickness) of the progress bar.
description?	React.ReactNode | Array<React.ReactNode>		all	Optional descriptive text below the progress bar. If multiple items are provided in an array, they will be automatically rotated every 2000 milliseconds. Single items are returned as-is without rotation.
formatValue?	'number' | 'fraction' | 'percentage' | (value: number, maxValue?: number) => string		all	Optional formatting of progress value text. If undefined, no progress value is displayed.
showIcon?	boolean	false	all	When true, displays icon next to progress value. If variant is 'success', the icon only appears when progress reaches 100%.
variant?	'info' | 'success' | 'warning' | 'error'	'info'	all	Optional variant of the progress bar. Defaults to 'info'.
isIndeterminate?	boolean	false	all	When true, shows an infinite looping animation along the bar instead of a specific width. Only available for info and success variants.
role?	'progressbar' | 'meter'	'progressbar'	determinate only	If determinate, specify role of the progress bar ("progressbar" or "meter"). Defaults to "progressbar".
value	number		all	Current progress value. Optional only if isIndeterminate is true.
maxValue?	number		determinate only	If determinate, specify maximum progress value.
enableAnimation?	boolean	false	determinate with role "progressbar" only	When true, enables shimmer animation for longer-running processes. Only available for determinate bars with role "progressbar". Only available for info and success variants.
disabled?	boolean	false	determinate only	When true, shows a disabled style and pauses animation.

Test Harnesses

getTestUtils

getTestUtils() exposes helper functions to access inner elements of the ProgressBar component for testing.

Single ProgressBar

import { getTestUtils } from '@leafygreen-ui/progress-bar/testing';

test('renders single progress bar', () => {
  // ...code to render a progress bar

  const { getBar } = getTestUtils();

  expect(getBar()).toBeInTheDocument();
});

Multiple ProgressBar components

import { getTestUtils } from '@leafygreen-ui/progress-bar/testing';

test('renders multiple progress bars', () => {
  // ...code to render multiple progress bars

  const utilsOne = getTestUtils('lg-progress_bar_1');
  const utilsTwo = getTestUtils('lg-progress_bar_2');

  expect(utilsOne.getBar()).toBeInTheDocument();
  expect(utilsTwo.getBar()).toBeInTheDocument();
});

Test Utils

const {
  getContainer,
  getBar,
  getBarFill,
  getBarTrack,
  queryIcon,
  queryLabel,
  queryDescription,
  queryValueText,
} = getTestUtils();

Util	Description	Returns
getContainer	Returns the root element containing the progress bar and all accompanying text.	HTMLDivElement
getBar	Returns the progress bar element, which can have either role="progressbar" or role="meter" depending on usage.	HTMLDivElement
getBarFill	Returns the fill element of the progress bar.	HTMLDivElement
getBarTrack	Returns the track element of the progress bar.	HTMLDivElement
queryIcon	Returns the icon element, if present.	HTMLDivElement | null
queryLabel	Returns the label element, if present.	HTMLDivElement | null
queryDescription	Returns the description element, if present.	HTMLDivElement | null
queryValueText	Returns the value text element, if present.	HTMLDivElement | null