Correct and idiomatic ways to use the <mds-progress> component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in agents/variants.md and the shared component rules in agents/conventions.md.

Basic Horizontal Progress Bar

The default form. Pass progress as a fractional value between 0 and 1. The component exposes role="progressbar" and manages aria-valuenow automatically.

<mds-progress progress="0.4" aria-label="Caricamento documento"></mds-progress>

Variant for Semantic Meaning

Use variant to communicate the nature of the task - not just the colour you want. The component maps every ThemeVariantType value to a matching color pair for the fill and track.

<!-- Operazione riuscita -->
<mds-progress progress="1" variant="success" aria-label="Importazione completata"></mds-progress>

<!-- Operazione con avviso -->
<mds-progress progress="0.6" variant="warning" aria-label="Quota disco in esaurimento"></mds-progress>

<!-- Errore -->
<mds-progress progress="0.85" variant="error" aria-label="Errore di rete"></mds-progress>

<!-- Contenuto AI -->
<mds-progress progress="0.5" variant="ai" aria-label="Elaborazione AI in corso"></mds-progress>

Sizing

Use the size prop to control the thickness of the bar. sm is the default and suits most inline uses; larger values give more visual weight in dashboard or hero contexts.

<mds-progress progress="0.5" size="sm" aria-label="Piccola barra"></mds-progress>
<mds-progress progress="0.5" size="md" aria-label="Barra media"></mds-progress>
<mds-progress progress="0.5" size="lg" aria-label="Barra grande"></mds-progress>
<mds-progress progress="0.5" size="xl" aria-label="Barra extra grande"></mds-progress>

Vertical Progress Bar

Set direction="vertical" for upward-fill layouts such as column charts or skill meters. Give the host an explicit height via CSS because the element stretches to fit its container.

<mds-progress
  progress="0.65"
  direction="vertical"
  variant="primary"
  aria-label="Utilizzo CPU"
  style="height: 120px;"
></mds-progress>

Radial Progress Bar

Set direction="radial" to render a circular ring with a centered percentage label via the internal mds-radial-progress component. Control the ring diameter through a CSS width on the host.

<mds-progress
  progress="0.72"
  direction="radial"
  variant="primary"
  aria-label="Completamento profilo"
  style="width: 80px;"
></mds-progress>

Radial with Typography Control

When direction="radial", the typography prop selects the type scale applied to the centered percentage label. Use 'label' for denser layouts and 'option' (default) for standard sizing.

<mds-progress
  progress="0.5"
  direction="radial"
  typography="label"
  aria-label="Avanzamento attivita"
  style="width: 64px;"
></mds-progress>

Accessible Step Labels

The steps prop is a comma-separated list of milestone strings. As progress changes the component picks the nearest label and sets aria-valuetext, so screen readers announce a meaningful milestone rather than a raw number. Provide labels that match the granularity of your task.

<mds-progress
  progress="0.5"
  steps="Inizializzazione,Analisi,Elaborazione,Completamento"
  variant="primary"
  aria-label="Avanzamento analisi dati"
></mds-progress>

Decorative Use (aria-hidden)

When <mds-progress> is used purely as a visual indicator alongside a separate text description, set aria-hidden="true". The component removes all progressbar ARIA attributes so assistive technologies skip it.

<p>Progresso: 40%</p>
<mds-progress progress="0.4" aria-hidden="true"></mds-progress>

Updating Progress Dynamically

Set the progress property from JavaScript as the task advances. The component transitions the fill with --mds-progress-duration and updates aria-valuenow and aria-valuetext on each change.

const bar = document.querySelector('mds-progress');

async function runTask() {
  for (let i = 0; i <= 10; i++) {
    await doWork(i);
    bar.progress = i / 10;
  }
}

Styling Customization

Override the documented --mds-progress-* CSS custom properties for one-off visual tweaks. Name a semantic role, rgb(var(--magma-<role>)) (agents/color.md), so dark mode keeps working.

.upload-widget mds-progress {
  --mds-progress-background: rgb(var(--magma-wash-base));
  --mds-progress-color: rgb(var(--magma-accent-emphasis-hover));
  --mds-progress-thickness: 16px;
  --mds-progress-duration: 400ms;
}