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

Basic Progress Indicator

The minimal form. Pass progress as a fraction between 0 and 1; the component renders the ring and displays the whole-number percentage at its center.

<mds-radial-progress progress="0.65"></mds-radial-progress>

Variant for Semantic Coloring

Use variant to communicate what kind of progress is being tracked. Pick a brand value for neutral steps and a status value to express the outcome color.

<!-- Neutral brand progress -->
<mds-radial-progress progress="0.4" variant="primary"></mds-radial-progress>

<!-- Success state - caricamento completato -->
<mds-radial-progress progress="1" variant="success"></mds-radial-progress>

<!-- Warning - procedura parziale -->
<mds-radial-progress progress="0.3" variant="warning"></mds-radial-progress>

<!-- Error - operazione fallita -->
<mds-radial-progress progress="0.15" variant="error"></mds-radial-progress>

<!-- AI variant - elaborazione AI in corso -->
<mds-radial-progress progress="0.72" variant="ai"></mds-radial-progress>

Progress with Icon

Set icon to an icon slug to show a glyph above the percentage readout. The icon takes the same color as the ring.

<!-- Caricamento file -->
<mds-radial-progress
  progress="0.55"
  icon="mi/baseline/cloud-upload"
  variant="primary"
></mds-radial-progress>

<!-- Stato di salvataggio -->
<mds-radial-progress
  progress="0.9"
  icon="mi/baseline/save"
  variant="success"
></mds-radial-progress>

Typography Scale

typography controls the type token used for the centered percentage. Use 'option' (default) for most sizes and 'label' when the ring is rendered at a smaller size and a tighter type scale is needed.

<!-- Default - token "option" -->
<mds-radial-progress progress="0.5" typography="option"></mds-radial-progress>

<!-- Compact version - token "label" -->
<mds-radial-progress progress="0.5" typography="label"></mds-radial-progress>

Controlling Size via CSS

<mds-radial-progress> is sized by its width (the host uses a 1:1 aspect-ratio). Set the width on the host; do not set height separately.

.dashboard-kpi mds-radial-progress {
  width: 96px;
}

.compact-cell mds-radial-progress {
  width: 32px;
}

Live Updates and Animation

Bind progress to a reactive state value. When the prop changes, the component smoothly animates the ring to the new value over ~500 ms using an ease-out curve. Respects the reduced-motion preference (the Magma pref-animation-* choice, or the OS setting when it follows the system) automatically - no extra code needed.

<mds-radial-progress id="upload-ring" progress="0"></mds-radial-progress>

<script>
  const ring = document.getElementById('upload-ring');
  // Simulate upload progress
  let value = 0;
  const interval = setInterval(() => {
    value = Math.min(1, value + 0.1);
    ring.progress = value;
    if (value >= 1) clearInterval(interval);
  }, 300);
</script>

Dark and Light Neutral Variants

variant="dark" paints an inverse ring (surface-inverse: dark on a light UI, light on a dark one); variant="light" paints a neutral ring on the wash. Both use neutral roles that follow the mode, so they adapt without custom CSS and are not tied to a light or dark background.

<!-- Anello invertito -->
<mds-radial-progress progress="0.6" variant="dark"></mds-radial-progress>

<!-- Anello neutro -->
<mds-radial-progress progress="0.6" variant="light"></mds-radial-progress>

Shadow Part Customization

The component documents no CSS custom properties: color it with variant, and use the two documented shadow parts - value-container and icon - for deeper styling.

/* Adjust the inner circle shadow */
mds-radial-progress::part(value-container) {
  box-shadow: none;
}

/* Tint the icon independently from the ring color */
mds-radial-progress::part(icon) {
  fill: rgb(var(--magma-warning-text-default));
}