Use a determinate progress bar when completion can be calculated against a known total. Use
indeterminate only when the duration or completion cannot be determined.When to use
Use progress bars when
- The task has a measurable duration and a defined completion point
- Real-time feedback helps users understand how long they need to wait
- You need to communicate progress, completion, or error state visually
- A spinner would feel too vague because the work can be quantified
Do not use progress bars when
- The task completes instantly and no waiting feedback is needed
- Progress cannot be tracked reliably and a determinate bar would be misleading
- A spinner or loading skeleton is a better fit for the context
- The bar would compete with the main content instead of supporting it
Patterns
With percentage
Show the progress value when users need a clear percentage in addition to the visual bar.
With tooltip
Use a tooltip when you want the progress value attached to the indicator instead of displayed beside the bar.
Determinate
Use a determinate progress bar when the task can be measured against a known completion point.
Indeterminate
Use an indeterminate progress bar when work is in progress but the exact completion point cannot be determined.
Top page progress bar
A progress bar can also appear at the top of the page to communicate loading or update status without interrupting the main content.
Anatomy
| Part | Element | Description |
|---|---|---|
| 1 | Bar indicator | The filled portion showing the current progress value |
| 2 | Track | The background rail representing the full available range |
| 3 | Value | The percentage detail shown when the progress value is exposed to the user |
Design guidelines
Choose the progress treatment that matches how precise the feedback needs to be.Choose the feedback type
Start with a determinate bar whenever progress can be measured. Switch to
indeterminate only when the task is active but cannot be quantified.Choose the emphasis
Use
medium thickness by default. Use large only when the progress bar needs stronger visual emphasis in a prominent area.When
indeterminate is enabled, label and enable-tooltip do not render a percentage, because the component cannot represent a specific completion value.Usage
Default
Use the default progress bar for general task tracking when the process has a measurable completion point.Options
Large thickness
Usethickness="large" to increase the visual weight of the progress bar in more prominent layouts.
Error
Usetype="error" to communicate that a process failed or needs attention.
Border shape
Useborder-shape="square" when you want a straighter edge treatment. The default is rounded.
With label
Addlabel to display a persistent numeric percentage beside the bar.
With tooltip
Addenable-tooltip to show the current percentage at the indicator. In the current component implementation, the tooltip stays visible while the option is enabled.
Indeterminate
Useindeterminate when the task is active but the exact completion point cannot be measured.
Best practices
DoPlace descriptive text close to the progress bar so people immediately understand what is being tracked.
Don’tDo not embed text inside the bar itself. It becomes unreadable at low progress values and is harder to interpret accessibly.
DoUse
label or enable-tooltip when users need a precise sense of how much work remains.Don’tDo not use a determinate progress bar when progress cannot actually be measured. That creates false certainty.
DoPair
type="error" with a visible message so users who cannot perceive color still understand the failure.Don’tDo not rely on color alone to communicate error state. Not all users perceive color distinctions.
DoUse
indeterminate only when the duration genuinely cannot be measured. Switch to a determinate bar as soon as progress can be tracked.Don’tDo not use an indeterminate bar as a substitute when a determinate bar is technically possible. It creates unnecessary uncertainty.
Accessibility
- Built-in progress semantics — the component renders a native
<progress>element inside its shadow DOM, which browsers expose asrole="progressbar"witharia-valuenow,aria-valuemin="0", andaria-valuemax="100"automatically. Assistive technology reads the current value without additional markup. - Indeterminate state — when
indeterminateistrue, the native element has novalueattribute, and assistive technology announces it as an indeterminate progress bar. - Provide task context: add a visible label or nearby text that explains what operation the progress bar is tracking.
- Do not rely on color alone: pair
type="error"with a visible message so the failure state is understandable without color perception. - Use percentage only when it helps:
labelorenable-tooltipimproves clarity when precise status matters, but it is not required for every short or self-explanatory task. - Be careful with motion: if indeterminate animation is distracting in your application, respect
prefers-reduced-motionat the app level.
API reference
Properties
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
borderShape | border-shape | Sets the border style of the progress bar | "rounded" | "square" | "rounded" |
enableTooltip | enable-tooltip | If true, a tooltip showing the current value is rendered at the indicator | boolean | false |
indeterminate | indeterminate | If true, the indeterminate animation is shown and value is ignored | boolean | false |
label | label | If true, a percentage label is rendered beside the bar | boolean | false |
thickness | thickness | Controls the height of the bar | "medium" | "large" | "medium" |
type | type | Sets the visual type of the progress bar | "default" | "error" | "default" |
value | value | The current progress value, clamped between 0 and 100 | number | 0 |
Shadow parts
| Part | Description |
|---|---|
base | The base container for the internal bq-tooltip component |
indeterminate | The <div> container that holds the animated indeterminate indicator |
label | The <div> container that holds the label value in percentage |
panel | The container holding the tooltip content |
progress | The <div> container that holds the native <progress> element |
progress-bar | The native <progress> element |
trigger | The element that triggers the internal tooltip placement |
wrapper | The component wrapper container inside the shadow DOM |
CSS custom properties
| Variable | Description | Default |
|---|---|---|
--bq-progress-bar--height | The progress bar height | 0.25rem |
--bq-progress-bar--indeterminateWidth | The width of the moving indicator when indeterminate | 25% |
--bq-progress-bar--indicatorColor | The filled indicator color | var(--bq-ui--brand) |
--bq-progress-bar--trackColor | The track color | var(--bq-ui--secondary) |
Resources
Interactive playground
Explore progress bar examples and states in Storybook.
Source code
Browse the component implementation, styles, and tests on GitHub.