On this page

Data & status

Progress released

How far along a task is — or, when nobody can say, that it is under way at all.

Import@pacit/components/progress
Selectorpct-progress

No APG pattern applies, and none is invented — the reasoning is under Accessibility ↓

import { Component, signal } from '@angular/core';
import { PctButton } from '@pacit/components/button';
import { PctProgress } from '@pacit/components/progress';

/** With a value it reports the number; without one it honestly says "still working". */
@Component({
  selector: 'demo-progress',
  imports: [PctButton, PctProgress],
  // A width, not only a ceiling: a bar 100% of a container that is as wide as its content
  // is a bar as wide as the button beside it (`lesson-160`).
  styles: ':host { display: grid; gap: 12px; inline-size: min(24rem, 100%); }',
  template: `
    <pct-progress [value]="done()" ariaLabel="Uploading" />
    <pct-progress ariaLabel="Connecting" />
    <div>
      <button pctButton variant="ghost" size="sm" (click)="move(-10)">
        −10
      </button>
      <button pctButton variant="ghost" size="sm" (click)="move(10)">
        +10
      </button>
    </div>
  `,
})
export class ProgressDemo {
  readonly done = signal(62);

  move(by: number): void {
    this.done.update((at) => Math.min(100, Math.max(0, at + by)));
  }
}

progress.demo.ts — the same file runs here and is highlighted under Code

Start here

Usage

One import per component, and the shortest possible use — the package itself is installed once, on the start page.

Import this component

import { PctProgress } from '@pacit/components/progress';

Exported	What it is
`PctProgress`component`pct-progress`	A progress bar: how far along a task is, or that it is under way at all.

<pct-progress [value]="42" ariaLabel="Uploading" />

Examples

Every state, running

Each example is the component itself, not a screenshot. Open the code under any of them.

Determinate, indeterminate, and the sizes

A value makes the bar say how far; no value makes it say "still going", and the fill travels instead. max sets the scale — a download in bytes needs no arithmetic first.

API

What it reads, and what it writes back

Read from the source at build time — the types, the defaults and the lines of documentation are the library's own.

A progress bar: how far along a task is, or that it is under way at all.

Inputs

Name	Type	What it does
`value`default `null`	`number \| null`	How far along, in the same unit as `max`. `null` — the default — is indeterminate: the task is under way and how far is not known.
`max`default `DEFAULT_MAX`	`number`	The value that means "done" — `100` by default, so a bare `[value]="40"` is forty per cent.
`ariaLabel`default `''`	`string`	The accessible name — what is progressing. There is no default: see the class note.
`ariaLabelledby`default `''`	`string`	The `id` of the element that already names this bar — a caption or a heading standing beside it. The usual case: the sentence a sighted user reads is the name a screen-reader user should hear, and repeating it in `ariaLabel` is two strings to keep in step.
`size`default `config.defaultSize`	`PctSize`	Size; taken from the global configuration by default (`req-api-config`).
`tone`default `null`	`PctTone \| null`	What the work IS, drawn as a mark beside the bar and as the colour of the fill — not how far it got, which is `value`. A failed upload is `tone: 'danger'` at whatever percentage it stopped at; a finished one is `'success'` at 100. An indeterminate bar may carry a tone too: "retrying, and the last attempt failed" is a real state, and nothing here pretends to know what the work will do next.

Outputs

None of its own. The native events — (click), (focus), the form's submit — are the platform's, and two-way models above carry the rest.

What it writes on the element

The hooks a stylesheet or a test can hold. Stable by contract — the parts inventory gate fails the build when one disappears.

Attribute	Bound to	Note
`class`	`pct-progress`
`data-pct-size`	`size()`
`data-pct-indeterminate`	`value() === null ? "" : null`	The state a skin reads, and the one the stylesheet's band rule turns on. It is written where the paint is — the ARIA half of the same fact is the `<progress>`'s own, and this component writes no ARIA anywhere (0039).
`data-pct-tone`	`tone()`

Styling

Parts to select, tokens to override

Two ways in, both stable. No class names to depend on.

Parts

In a test, PctProgressHarness from @pacit/components/testing reads a part by the name below and a state by its attribute — the harness gate holds the names to the package.

Part	Selector	What it is
`bar`	`[data-pct-part="bar"]`	the box that clips — the groove and the fill live inside it
`fill`	`[data-pct-part="fill"]`	the part that is done
`icon`	`[data-pct-part="icon"]`	the tone's mark, drawn only when the bar carries a tone
`track`	`[data-pct-part="track"]`	the full length

Tokens

Every value the component reads, with the light and the dark default. Override a token at any scope and it cascades like any custom property.

Token	Styles
`--pct-progress-fill-bg{pct.primary}`#2563eb · #60a5fa	Background of the fill.
`--pct-progress-fill-bg-danger{pct.danger}`#b91c1c · #f87171	Colour of the filled part of a bar whose work failed.
`--pct-progress-fill-bg-info{pct.info}`#2563eb · #60a5fa	Colour of the filled part of a bar reporting something informational.
`--pct-progress-fill-bg-success{pct.success}`#15803d · #4ade80	Colour of the filled part of a bar whose work succeeded.
`--pct-progress-fill-bg-warning{pct.warning}`#b45309 · #fbbf24	Colour of the filled part of a bar whose work needs attention.
`--pct-progress-fill-size`33%	Length of the fill while indeterminate, as a share of the track.
`--pct-progress-icon-gap{pct.space.2}`4px	Space between the tone's mark and the bar.
`--pct-progress-icon-size`16px	Size of the box the tone's mark is drawn in, beside the bar.
`--pct-progress-track-bg{pct.border}`#e2e8f0 · #334155	Background of the track.
`--pct-progress-track-height`8px	Height of the track.
`--pct-progress-track-height-lg`12px	Height of the track at size lg.
`--pct-progress-track-height-sm`4px	Height of the track at size sm.
`--pct-progress-track-radius`999px	Corner radius of the track.

Theming

A brand override in a few declarations. Scope it to a theme attribute, a page or one container — the component never notices.

[data-theme='brand'] {
  --pct-progress-fill-bg: #0f766e;
  --pct-progress-track-bg: #ccfbf1;
}

Accessibility

Measured, not assumed

Pattern: none — there is no APG pattern for a progress bar. What there is is the progressbar role, and this component does not write it: the bar is a <progress>, so the role, the bounds, the value and the indeterminate state are the element's. Named in the class JSDoc.

Keyboard

key	effect	test

Empty by design, and for a stronger reason than usual: a progress bar is not a control. Nothing is pressed, nothing is dragged, and a <progress> takes focus in no engine — measured in apps/sandbox-e2e/src/progress.spec.ts, which asks the element to focus itself and asserts that it does not, then walks Tab past it (req-api-platform).

Evidence

What the repository holds for this component

Read at build time from the tracked snapshots, not typed here.

92.31%mutation score48 of 52 mutants killed

11 × 3e2e cases × enginesplus the shared audits: axe, forced colors, preferences, size, hydration

11colour pairs measuredlight and dark, at every token build

2visual baselinesChromium, the sandbox's own pictures

13elements in the preview2 listeners · 1 render to settle · 3770 µs in jsdom, held exactly but for the clock

Why it is built this way

The whole component is one boundary drawn twice (0049): the platform's element for what a reader hears, our own drawing for what an eye sees. It is the checkbox's shape one component over, and it is here for a measured reason rather than a stylistic one — appearance: none is the price of painting a <progress>, and it takes the engine's indeterminate animation away.

Known limitations

No circular variant. A ring is a different drawing with its own tokens, and one already exists inside pct-button for a button that is working. A standalone one is a tag of its own when somebody needs it.
No buffer or second value. The platform's element has one value. A media player's buffered range is a second bar, and this component does not pretend to be two.
A tone is not announced. It reaches the eye and no further: pct-icon is aria-hidden, so a screen-reader user hears the <progress> and the consumer's own sentence beside it and nothing about success or failure. If a tone has to be heard, it belongs in that sentence — which is what ariaLabelledby points at — and not in a string this component invented (0039). Until 2026-09-07 this row said there were no tones at all, and the reason it gave was the right one: the second channel is an icon, four names into PctIconName at once, and a set no single component could judge. Two components wanted the same four, and the set is 0076's.
Nothing is announced. A determinate bar that spoke every percent would be noise, and the role is one assistive technology polls. An application that needs "upload complete" said out loud has a sentence to announce, and the sentence is not the bar.
The name is required and nothing enforces it at build time. A consumer who supplies neither ariaLabel nor ariaLabelledby gets a dev-mode warning and an axe violation on their own page; this repository's static gate can only see its own templates.

pacit

Usage

Every state, running

Determinate, indeterminate, and the sizes

What it reads, and what it writes back

Inputs

Outputs

What it writes on the element

Parts to select, tokens to override

Parts

Tokens

Theming

Measured, not assumed

Keyboard

What is measured, and what is not yet

What the repository holds for this component

Why it is built this way

Known limitations