Primitives

Progress

A bar that reflects the completion progress of a task.

forty-cdk/progress WAI-ARIA APG

The bar reflects data-value against data-min / data-max and moves data-state between loading, complete and indeterminate.

Source

60%

import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { ForProgress, ForProgressIndicator } from 'forty-cdk/progress';

@Component({
  selector: 'app-progress-default-example',
  changeDetection: ChangeDetectionStrategy.OnPush,
  imports: [ForProgress, ForProgressIndicator],
  template: `
    <div class="row">
      <div forProgress class="track" [value]="value()" [max]="100" announceCompletion>
        <div forProgressIndicator class="indicator"></div>
      </div>
      <span class="value">{{ value() }}%</span>
    </div>
  `,
  styles: `
    :host {
      display: contents;
    }

    .row {
      width: min(380px, 100%);
      display: flex;
      align-items: center;
      gap: 1rem;
    }

    .track {
      flex: 1;
      height: 10px;
      border-radius: 999px;
      background: var(--ex-border-strong, #d0c9bc);
      overflow: hidden;
    }

    .indicator {
      height: 100%;
      width: var(--for-progress-percentage, 0%);
      border-radius: 999px;
      background: var(--ex-accent, #0e7c6b);
      transition: width 0.3s ease;
    }

    .indicator[data-state='complete'] {
      background: #22c55e;
    }

    .value {
      min-width: 3.5ch;
      font-variant-numeric: tabular-nums;
      font-weight: 600;
      text-align: right;
    }

    @media (prefers-reduced-motion: reduce) {
      .indicator {
        transition: none;
      }
    }
  `,
})
export class ProgressDefaultExample {
  protected readonly value = signal(60);
}

Pass a numeric value for a determinate bar, or null for indeterminate ("loading…"). The directive owns ARIA + state; the visual fill is yours via [forProgressIndicator].

When to choose

Progress: role="progressbar", for a task advancing toward completion. value accepts null for the indeterminate "working…" state, and announceCompletion announces the end of the task.
Meter: role="meter", for a measurement inside a known range (disk used, battery, score), always determinate and bucketed into quality bands. Screen readers announce the two roles differently, so the choice is meaning rather than appearance: if the number is not going anywhere, it is a meter.

Anatomy

<div forProgress [value]="uploaded()" [max]="100" announceCompletion>
  <div forProgressIndicator></div>
</div>

Examples

Indeterminate

A null value puts the bar in indeterminate mode, for loading states whose duration cannot be predicted. In that mode aria-valuenow is omitted and data-state reflects indeterminate.

Source

…

import { ChangeDetectionStrategy, Component } from '@angular/core';
import { ForProgress, ForProgressIndicator } from 'forty-cdk/progress';

@Component({
  selector: 'app-progress-indeterminate-example',
  changeDetection: ChangeDetectionStrategy.OnPush,
  imports: [ForProgress, ForProgressIndicator],
  template: `
    <div class="row">
      <div forProgress class="track" [value]="null" [max]="100">
        <div forProgressIndicator class="indicator"></div>
      </div>
      <span class="value">…</span>
    </div>
  `,
  styles: `
    :host {
      display: contents;
    }

    .row {
      width: min(380px, 100%);
      display: flex;
      align-items: center;
      gap: 1rem;
    }

    .track {
      flex: 1;
      height: 10px;
      border-radius: 999px;
      background: var(--ex-border-strong, #d0c9bc);
      overflow: hidden;
    }

    .indicator {
      height: 100%;
      width: var(--for-progress-percentage, 0%);
      border-radius: 999px;
      background: var(--ex-accent, #0e7c6b);
    }

    .indicator[data-state='indeterminate'] {
      width: 40%;
      animation: progress-indef 1.2s ease-in-out infinite;
    }

    @keyframes progress-indef {
      0% {
        transform: translateX(-110%);
      }
      100% {
        transform: translateX(320%);
      }
    }

    .value {
      min-width: 3.5ch;
      font-variant-numeric: tabular-nums;
      font-weight: 600;
      text-align: right;
    }

    @media (prefers-reduced-motion: reduce) {
      .indicator[data-state='indeterminate'] {
        animation-duration: 0.01ms;
      }
    }
  `,
})
export class ProgressIndeterminateExample {}

Custom value label

getValueLabel maps value and max to a human string used for aria-valuetext, so screen readers announce '84 MB of 200 MB' instead of a bare number. The same function feeds the visible caption.

Source

project-assets.zip84 MB of 200 MB

import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { ForProgress, ForProgressIndicator } from 'forty-cdk/progress';

@Component({
  selector: 'app-progress-value-label-example',
  changeDetection: ChangeDetectionStrategy.OnPush,
  imports: [ForProgress, ForProgressIndicator],
  template: `
    <div class="upload">
      <div class="head">
        <span class="file">project-assets.zip</span>
        <span class="label">{{ label(uploaded(), total) }}</span>
      </div>
      <div forProgress class="track" [value]="uploaded()" [max]="total" [getValueLabel]="label">
        <div forProgressIndicator class="indicator"></div>
      </div>
    </div>
  `,
  styles: `
    :host {
      display: contents;
    }

    .upload {
      width: min(420px, 100%);
      display: flex;
      flex-direction: column;
      gap: 0.5rem;
    }

    .head {
      display: flex;
      justify-content: space-between;
      align-items: baseline;
      gap: 1rem;
    }

    .file {
      font-weight: 600;
    }

    .label {
      font-variant-numeric: tabular-nums;
      color: var(--ex-muted, #585d66);
    }

    .track {
      height: 10px;
      border-radius: 999px;
      background: var(--ex-border-strong, #d0c9bc);
      overflow: hidden;
    }

    .indicator {
      height: 100%;
      width: var(--for-progress-percentage, 0%);
      border-radius: 999px;
      background: var(--ex-accent, #0e7c6b);
      transition: width 0.3s ease;
    }

    .indicator[data-state='complete'] {
      background: #22c55e;
    }

    @media (prefers-reduced-motion: reduce) {
      .indicator {
        transition: none;
      }
    }
  `,
})
export class ProgressValueLabelExample {
  protected readonly total = 200;
  protected readonly uploaded = signal(84);

  protected readonly label = (value: number, max: number): string => `${value} MB of ${max} MB`;
}

API

`ForProgress`

Property	Type	Description
`value`	`input`	Current progress in `[0, max]` (one-way; display-only). `null` = indeterminate. Default: `null`
`max`	`input`	Upper bound. A non-positive `max` is clamped to `1` for ARIA so `aria-valuemax` always exceeds `aria-valuemin` (`0`). Default: `100`
`getValueLabel`	`input`	Override for `aria-valuetext` (e.g. "Step 3 of 5"). Default: —
`announceCompletion`	`input`	Announce `Complete` (or the label) once via `aria-live` on the loading→complete transition. Default: —
`ariaLabel`	`input`	Accessible name for the progressbar. Prefer a visible label referenced via `aria-labelledby` when one exists. Default: `null`

Data attribute	Values
`data-state`	`indeterminate` \| `loading` \| `complete`
`data-value`	clamped value (absent while indeterminate)
`data-min`	`0`
`data-max`	the `max` value
`data-percentage`	`0`–`100` (absent while indeterminate)

`ForProgressIndicator`

Visual fill paired with [forProgress]. Reflects the same state so width / transform can be driven from CSS, plus the --for-progress-percentage custom property (e.g. 25%) for use directly in transform / width.

Data attribute	Values
`data-state`	`indeterminate` \| `loading` \| `complete`
`data-value`	clamped value (absent while indeterminate)
`data-min`	`0`
`data-max`	the `max` value
`data-percentage`	`0`–`100` (absent while indeterminate)

Accessibility

Implements the WAI-ARIA Meter pattern, using the progressbar role.

role="progressbar" is announced as "progressbar" with the current value as a percentage (or your aria-valuetext if getValueLabel is set).
Indeterminate omits aria-valuenow. Per spec, the absence of aria-valuenow is what tells AT the bar is indeterminate. The directive enforces this; data-state="indeterminate" is the CSS hook.
Announce sparingly. announceCompletion is opt-in; only enable it on flows where the user explicitly waits for completion (uploads, submissions). For background activity, the silent state change is enough.
Keep the bar focusable only if it has actions. A vanilla [forProgress] is non-interactive and should not be in the tab order.

Styling

forty-cdk ships no styles: put your own class on each piece and key your CSS off the data-* attributes listed under API, not off the for* selectors (Styling forty-cdk explains why).

CSS custom properties

Property	Meaning
`--for-progress-percentage`	Completion as a CSS percentage (e.g. `25%`), set on `[forProgressIndicator]`. Absent while indeterminate (`value === null`).

.indicator[data-state='loading'] {
  width: var(--for-progress-percentage, 0%);
}

Wrapping in a design system

Subclass the root and re-provide FOR_PROGRESS_CONTEXT with useExisting pointing at the subclass, since Angular does not inherit a directive's providers; Wrapping non-form roots walks the pattern.