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.
import { GuiProgress } from '@golemui/gui-components/react';import '@golemui/gui-components/index.css';
export function ProgressBasic() { return <GuiProgress label="Uploading" value={40} showValue />;}import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';import '@golemui/gui-components/progress';
@Component({ selector: 'app-progress-basic', schemas: [CUSTOM_ELEMENTS_SCHEMA], template: ` <gui-progress label="Uploading" value="40" show-value></gui-progress> `,})export class ProgressBasicComponent {}<script setup lang="ts">import '@golemui/gui-components/progress';import '@golemui/gui-components/index.css';</script>
<template> <gui-progress label="Uploading" :value="40" :show-value="true"></gui-progress></template>import { LitElement, html } from 'lit';import { customElement } from 'lit/decorators.js';import '@golemui/gui-components/progress';import '@golemui/gui-components/index.css';
@customElement('progress-basic')export class ProgressBasic extends LitElement { protected override createRenderRoot() { return this; }
override render() { return html` <gui-progress label="Uploading" value="40" show-value></gui-progress> `; }}<gui-progress label="Uploading" value="40" show-value></gui-progress>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.
import { GuiProgress } from '@golemui/gui-components/react';import '@golemui/gui-components/index.css';
export function ProgressExample() { return ( <GuiProgress label="Uploading" value={40} showValue /> );}Add CUSTOM_ELEMENTS_SCHEMA to the component that uses the tags, and the stylesheet to styles in angular.json.
import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';import '@golemui/gui-components/progress';
@Component({ selector: 'app-progress-example', schemas: [CUSTOM_ELEMENTS_SCHEMA], template: ` <gui-progress label="Uploading" value="40" show-value ></gui-progress> `,})export class ProgressExampleComponent {}"styles": ["node_modules/@golemui/gui-components/lib/styles/index.css"]Tell Vue's compiler that gui-* tags are custom elements, and add the typings once for typed props and @gui-* handlers.
<script setup lang="ts">import '@golemui/gui-components/progress';import '@golemui/gui-components/index.css';</script>
<template> <gui-progress label="Uploading" value="40" show-value /></template>vue({ template: { compilerOptions: { isCustomElement: (tag) => tag.startsWith('gui-') } },});import type {} from '@golemui/gui-components/vue';The page's stylesheet styles the gui-* elements, so it only reaches them outside a shadow root. Render the host component into the light DOM too, as below, or load the stylesheet into its shadow root.
import { LitElement, html } from 'lit';import { customElement } from 'lit/decorators.js';import '@golemui/gui-components/progress';import '@golemui/gui-components/index.css';
@customElement('progress-example')export class ProgressExample extends LitElement { protected override createRenderRoot() { return this; }
override render() { return html` <gui-progress label="Uploading" value="40" show-value ></gui-progress> `; }}With any bundler, such as Vite. Import the element once, anywhere, and use the tag in your markup.
<gui-progress label="Uploading" value="40" show-value></gui-progress>
<script type="module" src="./main.js"></script>import '@golemui/gui-components/progress';import '@golemui/gui-components/index.css';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. |
Examples
Section titled “Examples”Indeterminate
Section titled “Indeterminate”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.
import { GuiProgress } from '@golemui/gui-components/react';import '@golemui/gui-components/index.css';
export function ProgressIndeterminate() { return <GuiProgress label="Waiting for the server" />;}import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';import '@golemui/gui-components/progress';
@Component({ selector: 'app-progress-indeterminate', schemas: [CUSTOM_ELEMENTS_SCHEMA], template: ` <gui-progress label="Waiting for the server"></gui-progress> `,})export class ProgressIndeterminateComponent {}<script setup lang="ts">import '@golemui/gui-components/progress';import '@golemui/gui-components/index.css';</script>
<template> <gui-progress label="Waiting for the server"></gui-progress></template>import { LitElement, html } from 'lit';import { customElement } from 'lit/decorators.js';import '@golemui/gui-components/progress';import '@golemui/gui-components/index.css';
@customElement('progress-indeterminate')export class ProgressIndeterminate extends LitElement { protected override createRenderRoot() { return this; }
override render() { return html` <gui-progress label="Waiting for the server"></gui-progress> `; }}<gui-progress label="Waiting for the server"></gui-progress>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.
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 />;}import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';import '@golemui/gui-components/progress';
@Component({ selector: 'app-progress-max', schemas: [CUSTOM_ELEMENTS_SCHEMA], template: ` <gui-progress label="Steps done" value="3" max="7" show-value ></gui-progress> `,})export class ProgressMaxComponent {}<script setup lang="ts">import '@golemui/gui-components/progress';import '@golemui/gui-components/index.css';</script>
<template> <gui-progress label="Steps done" :value="3" :max="7" :show-value="true" ></gui-progress></template>import { LitElement, html } from 'lit';import { customElement } from 'lit/decorators.js';import '@golemui/gui-components/progress';import '@golemui/gui-components/index.css';
@customElement('progress-max')export class ProgressMax extends LitElement { protected override createRenderRoot() { return this; }
override render() { return html` <gui-progress label="Steps done" value="3" max="7" show-value ></gui-progress> `; }}<gui-progress label="Steps done" value="3" max="7" show-value></gui-progress>Locale
Section titled “Locale”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.
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" />;}import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';import '@golemui/gui-components/progress';
@Component({ selector: 'app-progress-locale', schemas: [CUSTOM_ELEMENTS_SCHEMA], template: ` <gui-progress label="Subiendo" value="65" show-value locale-id="es" ></gui-progress> `,})export class ProgressLocaleComponent {}<script setup lang="ts">import '@golemui/gui-components/progress';import '@golemui/gui-components/index.css';</script>
<template> <gui-progress label="Subiendo" :value="65" :show-value="true" locale-id="es" ></gui-progress></template>import { LitElement, html } from 'lit';import { customElement } from 'lit/decorators.js';import '@golemui/gui-components/progress';import '@golemui/gui-components/index.css';
@customElement('progress-locale')export class ProgressLocale extends LitElement { protected override createRenderRoot() { return this; }
override render() { return html` <gui-progress label="Subiendo" value="65" show-value locale-id="es" ></gui-progress> `; }}<gui-progress label="Subiendo" value="65" show-value locale-id="es"></gui-progress>Progress from your code
Section titled “Progress from your code”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.
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> );}import { Component, CUSTOM_ELEMENTS_SCHEMA, signal } from '@angular/core';import '@golemui/gui-components/button';import '@golemui/gui-components/progress';
@Component({ selector: 'app-progress-task', schemas: [CUSTOM_ELEMENTS_SCHEMA], template: ` <div class="gui-grid"> <div class="gui-grid__cell"> <gui-progress label="Importing contacts" show-value [value]="done()" ></gui-progress> </div> <div class="gui-grid__cell"> <gui-button label="Import contacts" [loading]="running()" (click)="start()" ></gui-button> </div> </div> `,})export class ProgressTaskComponent { done = signal<number | undefined>(0); running = signal(false);
start() { this.running.set(true); // No value while it connects: the bar is indeterminate. this.done.set(undefined); let count = 0; // Stands in for the progress events of your upload or import. setTimeout(() => { const timer = setInterval(() => { count += 10; this.done.set(count); if (count === 100) { clearInterval(timer); this.running.set(false); } }, 300); }, 1000); }}<script setup lang="ts">import { ref } from 'vue';import '@golemui/gui-components/button';import '@golemui/gui-components/progress';import '@golemui/gui-components/index.css';
const done = ref<number | undefined>(0);const running = ref(false);
function start() { running.value = true; // No value while it connects: the bar is indeterminate. done.value = undefined; let count = 0; // Stands in for the progress events of your upload or import. setTimeout(() => { const timer = setInterval(() => { count += 10; done.value = count; if (count === 100) { clearInterval(timer); running.value = false; } }, 300); }, 1000);}</script>
<template> <div class="gui-grid"> <div class="gui-grid__cell"> <gui-progress label="Importing contacts" :value="done" :show-value="true" ></gui-progress> </div> <div class="gui-grid__cell"> <gui-button label="Import contacts" :loading="running" @click="start" ></gui-button> </div> </div></template>import { LitElement, html } from 'lit';import { customElement, state } from 'lit/decorators.js';import '@golemui/gui-components/button';import '@golemui/gui-components/progress';import '@golemui/gui-components/index.css';
@customElement('progress-task')export class ProgressTask extends LitElement { @state() private done: number | undefined = 0; @state() private running = false;
protected override createRenderRoot() { return this; }
private start() { this.running = true; // No value while it connects: the bar is indeterminate. this.done = undefined; let count = 0; // Stands in for the progress events of your upload or import. setTimeout(() => { const timer = setInterval(() => { count += 10; this.done = count; if (count === 100) { clearInterval(timer); this.running = false; } }, 300); }, 1000); }
override render() { return html` <div class="gui-grid"> <div class="gui-grid__cell"> <gui-progress label="Importing contacts" show-value .value=${this.done} ></gui-progress> </div> <div class="gui-grid__cell"> <gui-button label="Import contacts" ?loading=${this.running} @click=${this.start} ></gui-button> </div> </div> `; }}<div class="gui-grid"> <div class="gui-grid__cell"> <gui-progress id="import-progress" label="Importing contacts" value="0" show-value></gui-progress> </div> <div class="gui-grid__cell"> <gui-button id="import-start" label="Import contacts"></gui-button> </div></div>
<script type="module"> const progress = document.querySelector('#import-progress'); const start = document.querySelector('#import-start');
start.addEventListener('click', () => { start.loading = true; // No value while it connects: the bar is indeterminate. progress.value = undefined; let done = 0; // Stands in for the progress events of your upload or import. setTimeout(() => { const timer = setInterval(() => { done += 10; progress.value = done; if (done === 100) { clearInterval(timer); start.loading = false; } }, 300); }, 1000); });</script>Styling
Section titled “Styling”Anatomy
Section titled “Anatomy”<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> <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.
| Class | Part |
|---|---|
gui-label, gui-label__text | The label, and its text. |
gui-progress__value | The percentage at the end of the label’s line. Screen readers skip it: they read the bar. |
gui-progress__bar | The 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.
Tokens
Section titled “Tokens”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:
| Token | What it styles |
|---|---|
--gui-progress-height | The height of the bar. 0.5rem by default. |
--gui-progress-fill | The fill, and the band. var(--gui-intent-primary) by default. |
--gui-progress-track | The track behind the fill. var(--gui-border-strong) by default. |
--gui-radius-full | The rounded ends of the bar. |
--gui-space-1 | The space between the label and the bar. |
--gui-transition-normal | How 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.
/* 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.
Accessibility
Section titled “Accessibility”- Name. The
labelis 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-valueadds 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.