ProgressBar

When to useLink to "When to use"

• A task with a measurable amount (bytes, files, steps) that takes long enough to watch.
• A task in progress whose length is unknown, shown in place of the result: indeterminate.

Use something else when:

• the wait is short and inside a button: the Button's loading state
• a small inline busy indicator is enough: LoadingDots
• the person sets the value: a Slider

UsageLink to "Usage"

import { ProgressBar } from "@arshad-shah/cynosure";

<ProgressBar label="Uploading 3 files" value={uploaded} max={total} showValue />
<ProgressBar label="Preparing export" indeterminate />

Leave value out (or pass indeterminate) while the amount is unknown, then pass it once you know it. Values outside 0…max are clamped.

Value textLink to "Value text"

By default the value reads as a percentage. Pass labels.value to describe it in your own words; the same text is shown with showValue and read by screen readers.

A slim bar in a rowLink to "A slim bar in a row"

With labelHidden and no showValue, the bar is only its track: no label row, as tall as size makes it, and still named by label. Put it in a row of text (a query plan's cost, a quota beside its number) and give it the space with style={{ flex: 1 }}; it fills from the reading start in right-to-left text too.

<Inline gap="2" align="center">
  <Text size="sm">Seq Scan</Text>
  <ProgressBar label="Cost 1234.5" labelHidden value={45} size="sm" tone="warning" style={{ flex: 1 }} />
  <Text size="sm" tone="muted">cost: 1234.5</Text>
</Inline>

PropsLink to "Props"

Behaviour and accessibilityLink to "Behaviour and accessibility"

• Role: role="progressbar", named by label, with aria-valuemin, aria-valuemax, aria-valuenow and aria-valuetext. Indeterminate bars have no current value and are aria-busy.
• Announcements: a progress bar is not a live region. To announce completion, say so in the page (a Notice or a Toast).
• Contrast: the fill keeps at least 3:1 against its track in every tone, in light and dark modes.
• Direction: fills from the inline start, so from the right in right-to-left text.
• Motion: the fill eases between values; the indeterminate segment sweeps, and stands still in the middle under reduced motion.

ThemingLink to "Theming"

size sets the thickness: xs 2, sm 4, md 8 and lg 12 px. xs also sets smaller label and value text and a tighter gap, for dense desktop chrome.

Tokens: --cy-progress-bar-height-{xs,sm,md,lg}, --cy-progress-bar-radius and --cy-progress-bar-track.

createTheme({ components: { progressBar: { heightMd: "6px", radius: "2px" } } });

RelatedLink to "Related"

LoadingDots · Toast · Notice