> ## Documentation Index > Fetch the complete documentation index at: https://www.beeq.design/llms.txt > Use this file to discover all available pages before exploring further. # Progress > Progress bars visually represent the completion status of a task or process, giving users real-time feedback on how much has been done and what remains. export const CodeLivePreview = ({code, children, height, removePadding = false, mode = 'shadow'}) => { const previewRef = useRef(null); const BEEQ_ESM_URL = 'https://esm.sh/@beeq/core/dist/beeq/beeq.esm.js'; const BEEQ_CSS_URL = 'https://esm.sh/@beeq/core/dist/beeq/beeq.css'; const BEEQ_ICONS_URL = 'https://esm.sh/@beeq/core/dist/beeq/svg'; const ensureParentBeeqRuntime = () => { if (document.querySelector('script[data-beeq-parent-runtime]')) return; const script = document.createElement('script'); script.type = 'module'; script.src = BEEQ_ESM_URL; script.dataset.beeqParentRuntime = BEEQ_ICONS_URL; document.head.appendChild(script); }; const executeSnippetScripts = (root, runtimeWindow, previewRootArg, skipAttr) => { root.querySelectorAll('script').forEach(oldScript => { if (skipAttr && oldScript.hasAttribute(skipAttr)) return; if (oldScript.src) { const newScript = runtimeWindow.document.createElement('script'); newScript.src = oldScript.src; oldScript.replaceWith(newScript); return; } runtimeWindow.Function('previewRoot', oldScript.textContent || '')(previewRootArg); oldScript.remove(); }); }; const syncIframeMode = iframeDoc => { const root = document.documentElement; const explicitMode = root.getAttribute('bq-mode'); const isDark = root.classList.contains('dark'); const resolvedMode = explicitMode || (isDark ? 'dark' : 'light'); iframeDoc.documentElement.setAttribute('bq-mode', resolvedMode); iframeDoc.body.setAttribute('bq-mode', resolvedMode); }; useEffect(() => { if (mode === 'shadow') ensureParentBeeqRuntime(); }, [mode]); useEffect(() => { const container = previewRef.current; if (!container) return; if (removePadding) container.style.padding = '0'; container.innerHTML = ''; if (mode === 'iframe') { const iframe = document.createElement('iframe'); iframe.className = 'preview-iframe'; iframe.style.width = '100%'; iframe.style.border = '0'; iframe.style.display = 'block'; iframe.style.minHeight = height ?? '0px'; iframe.setAttribute('title', 'Live code preview'); iframe.setAttribute('loading', 'lazy'); iframe.setAttribute('sandbox', 'allow-scripts allow-same-origin'); container.appendChild(iframe); const iframeDoc = iframe.contentDocument; const iframeWin = iframe.contentWindow; if (!iframeDoc || !iframeWin) return; iframeDoc.open(); iframeDoc.write(['', '', '', ' ', ' ', ' ', ` `, ` `, '', '', code, '', ''].join('\n')); iframeDoc.close(); syncIframeMode(iframeDoc); const modeObserver = new MutationObserver(() => syncIframeMode(iframeDoc)); modeObserver.observe(document.documentElement, { attributes: true, attributeFilter: ['class', 'bq-mode'] }); executeSnippetScripts(iframeDoc, iframeWin, iframeDoc, 'data-beeq-iframe-runtime'); return () => modeObserver.disconnect(); } const shadowRoot = container.shadowRoot ?? container.attachShadow({ mode: 'open' }); if (!shadowRoot.adoptedStyleSheets.length) { const fixSheet = new CSSStyleSheet(); fixSheet.replaceSync(` bq-dropdown::part(panel), bq-panel::part(panel), bq-select::part(panel), bq-date-picker::part(panel) { z-index: 9999; } bq-tooltip::part(panel) { position: absolute; } `); shadowRoot.adoptedStyleSheets = [fixSheet]; } shadowRoot.innerHTML = [``, code].join(''); executeSnippetScripts(shadowRoot, window, shadowRoot); return undefined; }, [code, mode, height]); return
{}
{} {children &&
{children}
}
; }; export const CardTile = ({title, href, imageLightSrc, imageDarkSrc, children, enableImgZoom}) => { if (!href) { return
{imageLightSrc && {title}} {imageDarkSrc && {title}} {title &&

{title}

}
{children}
; } return {imageLightSrc && {title}} {imageDarkSrc && {title}} {title &&

{title}

}
{children}
; }; BEEQ Progress component overview BEEQ Progress component overview Progress bars communicate the status of ongoing tasks such as downloads, uploads, installations, or any operation with measurable completion. They reduce uncertainty by showing how much work is done and how much remains. 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 Show the progress value when users need a clear percentage in addition to the visual bar. Use a tooltip when you want the progress value attached to the indicator instead of displayed beside the bar. Use a determinate progress bar when the task can be measured against a known completion point. Use an indeterminate progress bar when work is in progress but the exact completion point cannot be determined. A progress bar can also appear at the top of the page to communicate loading or update status without interrupting the main content. ## Anatomy BEEQ Progress component anatomy BEEQ Progress component anatomy The progress component is made up of the track, the filled indicator, and the progress value when it is displayed. | 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. Add `label` or `enable-tooltip` when users need a clear numeric indication of how much work remains. Color changes such as `type="error"` should always be supported by nearby text that explains what happened. Start with a determinate bar whenever progress can be measured. Switch to `indeterminate` only when the task is active but cannot be quantified. Use `medium` thickness by default. Use `large` only when the progress bar needs stronger visual emphasis in a prominent area. Add `label` for persistent percentage text or `enable-tooltip` when you want the value attached to the indicator instead. 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. :host { flex-direction: column !important; align-items: center !important; gap: var(--bq-spacing-m) !important; } bq-progress { width: 250px; } `} > ```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqProgress } from "@beeq/react"; <> ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqProgress } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqProgress], template: ` ` }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ## Options ### Large thickness Use `thickness="large"` to increase the visual weight of the progress bar in more prominent layouts. :host { flex-direction: column !important; align-items: center !important; gap: var(--bq-spacing-m) !important; } bq-progress { width: 250px; } `} > ```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqProgress } from "@beeq/react"; <> ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqProgress } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqProgress], template: ` ` }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### Error Use `type="error"` to communicate that a process failed or needs attention. bq-progress { width: 250px; } `} > ```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqProgress } from "@beeq/react"; ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqProgress } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqProgress], template: `` }) export class AppComponent {} ``` ```vue Vue icon="vuejs" theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` Always pair a color change with a contextual message. Color alone is not enough to communicate an error state clearly to all users. ### Border shape Use `border-shape="square"` when you want a straighter edge treatment. The default is `rounded`. :host { flex-direction: column !important; align-items: center !important; gap: var(--bq-spacing-m) !important; } bq-progress { width: 250px; } `} > ```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqProgress } from "@beeq/react"; <> ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqProgress } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqProgress], template: ` ` }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### With label Add `label` to display a persistent numeric percentage beside the bar. :host { flex-direction: column !important; align-items: center !important; gap: var(--bq-spacing-m) !important; } bq-progress { width: 250px; } `} > ```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqProgress } from "@beeq/react"; <> ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqProgress } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqProgress], template: ` ` }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### With tooltip Add `enable-tooltip` to show the current percentage at the indicator. In the current component implementation, the tooltip stays visible while the option is enabled. :host { flex-direction: column !important; align-items: center !important; gap: var(--bq-spacing-m) !important; padding-block: var(--bq-spacing-xl) !important; } bq-progress { width: 250px; } `} > ```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqProgress } from "@beeq/react"; <> ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqProgress } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqProgress], template: ` ` }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` Choose `enable-tooltip` when you want the percentage anchored to the indicator instead of rendered as a separate inline label. ### Indeterminate Use `indeterminate` when the task is active but the exact completion point cannot be measured. bq-progress { width: 250px; } `} > ```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqProgress } from "@beeq/react"; ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqProgress } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqProgress], template: `` }) export class AppComponent {} ``` ```vue Vue icon="vuejs" theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ## Best practices Do Place descriptive text close to the progress bar so people immediately understand what is being tracked. Don't Do not embed text inside the bar itself. It becomes unreadable at low progress values and is harder to interpret accessibly. Do Use `label` or `enable-tooltip` when users need a precise sense of how much work remains. Don't Do not use a determinate progress bar when progress cannot actually be measured. That creates false certainty. Do Pair `type="error"` with a visible message so users who cannot perceive color still understand the failure. Don't Do not rely on color alone to communicate error state. Not all users perceive color distinctions. Do Use `indeterminate` only when the duration genuinely cannot be measured. Switch to a determinate bar as soon as progress can be tracked. Don't Do 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 `` element inside its shadow DOM, which browsers expose as `role="progressbar"` with `aria-valuenow`, `aria-valuemin="0"`, and `aria-valuemax="100"` automatically. Assistive technology reads the current value without additional markup. * **Indeterminate state** — when `indeterminate` is `true`, the native element has no `value` attribute, 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**: `label` or `enable-tooltip` improves 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-motion` at 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 `
` container that holds the animated indeterminate indicator | | `label` | The `
` container that holds the label value in percentage | | `panel` | The container holding the tooltip content | | `progress` | The `
` container that holds the native `` element | | `progress-bar` | The native `` 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)` | Learn more about [styling with shadow parts](/guides/styles#component-shadow-dom-parts) and [CSS custom properties](/guides/styles#global-css-custom-properties). ## Resources Explore progress bar examples and states in Storybook. Browse the component implementation, styles, and tests on GitHub.