Skip to content
Components, switch product

Progress

<gui-progress> shows how far a task has got, such as an upload or an import. It renders a native <progress> with its label above it, and can show the percentage at the end of the label’s line.

Code of the example above
ProgressBasic.tsx
import { GuiProgress } from '@golemui/gui-components/react';
import '@golemui/gui-components/index.css';
export function ProgressBasic() {
return <GuiProgress label="Uploading" value={40} showValue />;
}

The element’s entry point is @golemui/gui-components/progress, which registers <gui-progress> and nothing else. To install the package and load the stylesheet, see Installation.

The @golemui/gui-components/react components have typed props and an on* prop for each event. React 18 or later.

ProgressExample.tsx
import { GuiProgress } from '@golemui/gui-components/react';
import '@golemui/gui-components/index.css';
export function ProgressExample() {
return (
<GuiProgress
label="Uploading"
value={40}
showValue
/>
);
}

value goes from 0 to max, 100 by default. Give it a label: it names the bar for screen readers. It is not a form control, so it has no name and submits nothing.

Properties

Property Type Default Description
label string – Its name, shown above the bar. Screen readers read it with the value.
value number – How far the task has got, from 0 to max. Without it the bar is indeterminate.
max number 100 The value of a finished task. Defaults to 100.
showValue attribute show-value boolean false Shows the percentage at the end of the label's line, formatted in locale-id.
localeId attribute locale-id string 'en' BCP 47 locale for the percentage, such as en-US or es.
uid string – The id of the element's control. The ids of its label, hint and errors derive from it. Optional: when it is not set, the element generates one from its tag name and a page-wide counter, e.g. gui-textinput-3. Generated ids depend on creation order, so a server-rendered element must set uid or its ids will not match after hydration.
idPrefix attribute id-prefix string – Goes in front of every DOM id the element renders, so two elements with the same uid in different forms render different ids. GolemUI Forms sets it to the form's formName. Only ids and the references to them (for, aria-describedby…) take it: data-cy attributes and event details keep the bare uid.
domId read-only, no attribute string – The id of the element's control: uid, behind idPrefix when it is set.

Without a value, the bar is indeterminate: the task runs, and how far it has got is unknown. A band runs along the track, the other way in a right-to-left page, and slower when the system asks for reduced motion.

Code of the example above
ProgressIndeterminate.tsx
import { GuiProgress } from '@golemui/gui-components/react';
import '@golemui/gui-components/index.css';
export function ProgressIndeterminate() {
return <GuiProgress label="Waiting for the server" />;
}

max sets the value of a finished task, such as the number of steps. The bar and the percentage follow it: 3 of 7 is 43%. A value below 0 or above max shows as 0 or max, and a max that is not a positive number counts as 100.

Code of the example above
ProgressMax.tsx
import { GuiProgress } from '@golemui/gui-components/react';
import '@golemui/gui-components/index.css';
export function ProgressMax() {
return <GuiProgress label="Steps done" value={3} max={7} showValue />;
}

show-value formats the percentage in locale-id, en by default: Spanish writes “65 %”. In a right-to-left page, the percentage keeps its digits before its sign.

Code of the example above
ProgressLocale.tsx
import { GuiProgress } from '@golemui/gui-components/react';
import '@golemui/gui-components/index.css';
export function ProgressLocale() {
return <GuiProgress label="Subiendo" value={65} showValue localeId="es" />;
}

Set value as your task reports progress, such as the progress events of an upload. Clear it, undefined, while the task has started but reports nothing yet: the bar is indeterminate until the first value arrives.

Code of the example above
ProgressTask.tsx
import { useState } from 'react';
import { GuiButton, GuiProgress } from '@golemui/gui-components/react';
import '@golemui/gui-components/index.css';
export function ProgressTask() {
const [done, setDone] = useState<number | undefined>(0);
const [running, setRunning] = useState(false);
const start = () => {
setRunning(true);
// No value while it connects: the bar is indeterminate.
setDone(undefined);
let count = 0;
// Stands in for the progress events of your upload or import.
setTimeout(() => {
const timer = setInterval(() => {
count += 10;
setDone(count);
if (count === 100) {
clearInterval(timer);
setRunning(false);
}
}, 300);
}, 1000);
};
return (
<div className="gui-grid">
<div className="gui-grid__cell">
<GuiProgress label="Importing contacts" value={done} showValue />
</div>
<div className="gui-grid__cell">
<GuiButton label="Import contacts" loading={running} onClick={start} />
</div>
</div>
);
}

<gui-progress> renders into the light DOM, so you can style every part with plain CSS. These are the parts and their public classes, with show-value:

gui-progress
<gui-progress>
<label class="gui-label" for="upload" id="upload_label">
<span class="gui-label__text">Uploading</span>
<span class="gui-progress__value" aria-hidden="true">40%</span>
</label>
<progress
class="gui-progress__bar"
id="upload"
max="100"
value="40"
></progress>
</gui-progress>

The ids derive from uid, here upload, or from a generated id such as gui-progress-1 when you don’t set one.

ClassPart
gui-label, gui-label__textThe label, and its text.
gui-progress__valueThe percentage at the end of the label’s line. Screen readers skip it: they read the bar.
gui-progress__barThe native <progress>: the track, and the fill up to the value.

The bar draws its fill with each browser’s own pseudo-elements, ::-webkit-progress-value and ::-moz-progress-bar, and the band of an indeterminate bar as its background. Change the colors with the tokens below rather than with those selectors.

The progress bar reads these design tokens. Set them on :root to change every progress bar, or on any element to change the ones inside it:

TokenWhat it styles
--gui-progress-heightThe height of the bar. 0.5rem by default.
--gui-progress-fillThe fill, and the band. var(--gui-intent-primary) by default.
--gui-progress-trackThe track behind the fill. var(--gui-border-strong) by default.
--gui-radius-fullThe rounded ends of the bar.
--gui-space-1The space between the label and the bar.
--gui-transition-normalHow fast the fill moves to a new value.

The track and the fill reach a 3:1 contrast with the page, so the bar shows where it is even when it is empty. Keep that contrast when you change them.

styles.css
/* A thicker, green bar for the finished steps of the checkout. */
.checkout gui-progress {
--gui-progress-height: 0.75rem;
--gui-progress-fill: var(--gui-intent-success);
}

To restyle beyond the tokens, see Overriding styles; for dark mode and the Clay theme, see Themes and dark mode.

  • Name. The label is a <label> for the native <progress>, so screen readers read it as the bar’s name. Without a label the bar has no name: the element logs a warning in development builds.
  • Value. Screen readers read the value of a native progress bar as a percentage. The percentage that show-value adds is hidden from them, so they don’t read it twice.
  • Indeterminate. Without a value, the bar has no value, and screen readers read it as busy.
  • Changes. Screen readers don’t announce each new value as it changes: the user reads the bar when they reach it. To tell them the task has finished, announce it, for example with a toast.
  • Motion. With reduced motion, the fill moves to a new value at once, and the indeterminate band runs three times slower. It never stops: a band that stops would read as a task that stopped.

The bar takes no focus and has no keys of its own.

What every element shares is in Accessibility.