LeafyGreen UI Kit Progress Bar
npm install @leafygreen-ui/progress-barThe 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).
``shell`
pnpm add @leafygreen-ui/progress-bar
`shell`
yarn add @leafygreen-ui/progress-bar
`shell`
npm install @leafygreen-ui/progress-bar
`js
import ProgressBar from '@leafygreen-ui/progress-bar';
const [uploaded, setUploaded] = useState(0);
const [paused, setPaused] = useState(false);
const total = 100;
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}
/>;
`js
import ProgressBar from '@leafygreen-ui/progress-bar';
const [used, setUsed] = useState(96);
const totalSpaceAvailable = 128;
variant="warning"
label="Disk Space Used"
formatValue={(value: number, maxValue: number) =>
${value}/${maxValue} GB used`
}
value={used}
maxValue={totalSpaceAvailable}
/>;
`js
import ProgressBar from '@leafygreen-ui/progress-bar';
label="Loading report"
description="This might take a few seconds..."
/>;
`
| Prop | Type | Default | Applicable To | Description |
| ------------------ | ---------------------------------------------------------------------------------------------- | --------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| size? | 'small' \| 'default' \| 'large' | | all | Optional size (thickness) of the progress bar. |description?
| | React.ReactNode \| Array | | 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. |
getTestUtils() exposes helper functions to access inner elements of the ProgressBar component for testing.
#### Single ProgressBar
`tsx
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
`tsx
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();
});
`
`tsx`
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` |