GUILD OF GLEKS UIv21.19.0

gog-progressbar

Progress Bar

A horizontal progress indicator in three modes — determinate, indeterminate and buffer — five sizes and the library's semantic color set.

Overview

Import the component and drop it into a template.

typescript
import { ProgressbarComponent } from '@guildofgleks/ui';

@Component({
  // ...
  imports: [ProgressbarComponent],
})

Basic usage — a determinate bar, named for what it measures:

<gog-progressbar [value]="42" ariaLabel="Upload progress" />

Examples

Modes and sizes

determinate fills to value; buffer adds a lighter tier behind it for what has been fetched but not reached — a streaming or preload position; indeterminate sweeps a segment for work whose length is not known. Under prefers-reduced-motion the sweep stops and the bar is drawn striped instead, which still reads as "working". Five thickness steps, from a hairline to a chunky bar.

xsm · determinate

xsm · buffer

xsm · indeterminate

sm · determinate

sm · buffer

sm · indeterminate

md · determinate

md · buffer

md · indeterminate

lg · determinate

lg · buffer

lg · indeterminate

slg · determinate

slg · buffer

slg · indeterminate

@for (size of sizes; track size) {
  @for (mode of modes; track mode) {
    <div>
      <gog-progressbar
        [size]="size"
        [mode]="mode"
        [value]="40"
        [buffer]="70"
        ariaLabel="Uploading"
      />
      <p>{{ size }} · {{ mode }}</p>
    </div>
  }
}

Variants

accent is the default — progress is usually just "the app is working", which is not one of the four status hues. GogProgressbarVariant is an alias of GogSeverity, so these are the same five names gog-button's severity takes.

accent · determinate

accent · buffer

accent · indeterminate

info · determinate

info · buffer

info · indeterminate

success · determinate

success · buffer

success · indeterminate

warning · determinate

warning · buffer

warning · indeterminate

danger · determinate

danger · buffer

danger · indeterminate

@for (variant of variants; track variant) {
  @for (mode of modes; track mode) {
    <div>
      <gog-progressbar
        [variant]="variant"
        [mode]="mode"
        [value]="40"
        [buffer]="70"
        ariaLabel="Uploading"
      />
      <p>{{ variant }} · {{ mode }}</p>
    </div>
  }
}

Showing the value

Off by default, because a bar usually sits under a label that already says what it measures. On, the percentage prints beside the track in tabular figures, so the bar does not shift as the number changes. It is never shown in indeterminate mode, which has no number.

62%7%
<gog-progressbar [value]="62" showValue ariaLabel="Uploading" />
<gog-progressbar [value]="7" showValue ariaLabel="Uploading" />
<!-- Indeterminate has no number, so showValue prints nothing. -->
<gog-progressbar mode="indeterminate" showValue ariaLabel="Uploading" />

A value that moves, and one that overshoots

value and buffer are percentages, clamped to 0–100 rather than trusted: a bar driven straight from loaded / total overshoots on the last chunk often enough. Step past either end — the bar stops, and aria-valuenow with it, while the number you passed is kept as you passed it. The fill moves with a short transition, which reduced motion turns off.

20%

value: 20

[value]="-20"

0%

[value]="140"

100%

[value]="NaN"

0%
<gog-progressbar [value]="value()" showValue ariaLabel="Uploading" />
<div>
  <gog-button variant="outline" size="sm" (gogClick)="value.set(value() - 25)">−25</gog-button>
  <gog-button variant="outline" size="sm" (gogClick)="value.set(value() + 25)">+25</gog-button>
</div>
<p>value: {{ value() }}</p>

<!-- Clamped to 0–100 rather than trusted; NaN reads as 0. -->
@for (fixed of fixedValues; track $index) {
  <p>[value]="{{ fixed }}"</p>
  <gog-progressbar [value]="fixed" showValue ariaLabel="Uploading" />
}

Where the fill ends

With showValue off, the boundary between fill and track is the value, and WCAG 1.4.11 asks 3:1 of the part of a graphic that carries its meaning. Colour alone cannot always carry it: 51 of the 55 shipped fill/track combinations are below 3:1, because the five fills straddle mid-luminance and no single track colour clears all of them in any theme but primeng.

The edge marker

--gog-progressbar-edge-width is 0px by default 21.15.0. Set it to 1px — on :root, or on one bar — and two hairlines mark where the fill ends, and in buffer mode where the buffer ends: the theme's ink outermost against the track, the surface colour just inside the fill. Whichever tone a fill sits close to, the other one reads; the worst case across the eleven themes is 3.25:1. The grayscale columns are the same bars with hue taken away. The tones are --gog-progressbar-edge-color / -edge-backing-color, and they flip end under dir="rtl". Where the value has to be readable without colour, this or showValue is the consumer's call.

accent

accent, grayscale

accent, grayscale, edge 1px

info

info, grayscale

info, grayscale, edge 1px

success

success, grayscale

success, grayscale, edge 1px

warning

warning, grayscale

warning, grayscale, edge 1px

danger

danger, grayscale

danger, grayscale, edge 1px

@for (variant of variants; track variant) {
  <div>
    <gog-progressbar [variant]="variant" [value]="62" ariaLabel="Uploading" />
    <p>{{ variant }}</p>
  </div>
  <!-- The same bar with hue taken away: is the end of the fill still visible? -->
  <div style="filter: grayscale(1)">
    <gog-progressbar [variant]="variant" [value]="62" ariaLabel="Uploading" />
    <p>{{ variant }}, grayscale</p>
  </div>
  <div style="filter: grayscale(1); --gog-progressbar-edge-width: 1px">
    <gog-progressbar [variant]="variant" [value]="62" ariaLabel="Uploading" />
    <p>{{ variant }}, grayscale, edge 1px</p>
  </div>
}

Accessibility

role="progressbar" on the host, with the value stated as a number and as text, and no number at all when there is none.

  • Value — aria-valuemin / aria-valuemax, and in determinate and buffer mode aria-valuenow plus a readable aria-valuetext. buffer reports only value: the buffered tier is a picture, not a second number anyone needs read out.
  • Indeterminate leaves aria-valuenow out — that absence is what tells a screen reader the length is unknown; reporting 0 would announce "0 percent" for as long as it ran.
  • Keyboard — none. A progress bar is not focusable.

Every bar needs a name

ariaLabel is empty by default, and a bar with no name is announced as "progress bar, 62 percent" — of what, nobody says. Pass ariaLabel, or, when a visible label already sits beside the bar, point at it with aria-labelledby written on the host: the component binds none of its own, so yours reaches the element with the role. A <label for> cannot do it — a progress bar is not a form field. A bar with neither logs one console.warn per page in dev mode 21.19.0, never in production.

report.pdf

<gog-progressbar [value]="62" ariaLabel="Uploading report.pdf" />

<!-- A visible label beside the bar: point at it from the host. -->
<p id="progressbar-naming-label">report.pdf</p>
<gog-progressbar [value]="62" aria-labelledby="progressbar-naming-label" />

API Reference

Inputs

NameTypeDefaultDescription
valuenumber0Percentage complete, 0–100. Clamped rather than trusted — a bar driven from loaded / total overshoots on the last chunk often enough to be worth handling here. Ignored in indeterminate mode.
buffernumber0Secondary level shown behind value in buffer mode — preloaded but not yet played. Also clamped to 0–100.
mode'determinate' | 'indeterminate' | 'buffer''determinate'determinate reflects value; indeterminate is work of unknown length; buffer adds a second, lighter level ahead of the fill.
variant'accent' | 'success' | 'danger' | 'warning' | 'info''accent'Fill color. Wider than the tag palette by one: progress is usually just "the app is working", which is the accent color rather than any status hue.
size'xsm' | 'sm' | 'md' | 'lg' | 'slg''md'Bar thickness.
showValuebooleanfalseRenders the rounded percentage next to the bar. Off by default — most bars sit under a label that already says what is happening.
ariaLabelstring''What the bar measures ("Upload", "Storage used"). Unset, the host needs an aria-labelledby of your own; a bar with neither warns in dev mode (since 21.19.0).

Global Configuration

This component has no GOG_CONFIG entries of its own — every default is set per instance. See Global Configuration for what does apply app-wide.

Styling Tokens

Every CSS custom property the progress bar paints with. Override any of them — on a single instance, a subtree, or a theme — to restyle it. See the Theming guide for the full token-layering model, or the Theme Generator to tweak these live.

TokenDescription
--gog-progressbar-accent-bg / -success-bg / -danger-bg / -warning-bg / -info-bgFill color per variant.
--gog-progressbar-{variant}-buffer-bgThe lighter buffer level shown ahead of the fill in "buffer" mode.
--gog-progressbar-track-base-bg / -radiusThe unfilled track.
--gog-progressbar-{size}-heightBar thickness, per size step (xsm/sm/md/lg/slg).
--gog-progressbar-indeterminate-duration / -indeterminate-easingIndeterminate animation timing. Replaced by a static stripe under prefers-reduced-motion.
--gog-progressbar-stripe-color / -stripe-sizeThe static stripe that stands in for the animation when motion is reduced.
--gog-progressbar-value-color / -value-font-size / -value-min-width / -value-gapThe percentage readout rendered when showValue is on.
--gog-progressbar-edge-color / -edge-backing-color / -edge-widthTwo hairlines marking where the fill ends — and where the buffer level ends — off by default since 21.15.0 (-edge-width: 0px). Set the width to 1px to turn them on. The reason to: with showValue off, the boundary between fill and track is the only thing stating the value, and the fill and track colours alone do not clear WCAG 1.4.11’s 3:1 in every theme. On, they do — the ink line sits outermost against the track, the surface-coloured one just inside the fill. They are off because a light line on a dark fill reads as an outline rather than as the value.