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

Basic KPI Entry with Label and Description

The canonical form: a headline figure in label and a supporting caption in description, placed inside <mds-kpi>. Both props feed the item’s accessible spoken name automatically.

<mds-kpi>
  <mds-kpi-item
    label="1.240"
    description="Pratiche elaborate"
  ></mds-kpi-item>
</mds-kpi>

KPI Entry with an Icon

Add icon to display a visual marker above the figure. Use an icon slug from the Magma icon library - no .svg extension.

<mds-kpi>
  <mds-kpi-item
    label="98%"
    description="Soddisfazione clienti"
    icon="mi/baseline/thumb-up"
  ></mds-kpi-item>
</mds-kpi>

Multiple KPI Items in a Panel

Group related metrics by placing several <mds-kpi-item> elements as direct children of <mds-kpi>. The parent sets up the list role; each item registers as a listitem.

<mds-kpi>
  <mds-kpi-item label="3.500" description="Utenti attivi" icon="mi/baseline/group"></mds-kpi-item>
  <mds-kpi-item label="128" description="Servizi erogati" icon="mi/baseline/work"></mds-kpi-item>
  <mds-kpi-item label="99,9%" description="Disponibilita del sistema" icon="mi/baseline/check-circle"></mds-kpi-item>
</mds-kpi>

Scroll-Triggered Reveal Animation

Set threshold to a value between 0 and 1 to defer the yugop text animation until the item enters the viewport. A value of 0.5 means at least 50 % of the item must be visible before the animation starts. Use this for KPI strips placed lower on a landing page.

<mds-kpi>
  <mds-kpi-item
    label="45.000"
    description="Documenti archiviati"
    icon="mi/baseline/folder"
    threshold="0.5"
  ></mds-kpi-item>
</mds-kpi>

Label-Only KPI (No Description)

Omit description only when the figure is self-explanatory. The accessible name is still built as "{label}: {description}", so it reads 2026: undefined; ensure the surrounding context provides enough meaning.

<mds-kpi>
  <mds-kpi-item label="2026"></mds-kpi-item>
</mds-kpi>

Icon-Only Visual Accent (No Numeric Value)

Omit label and description to display only the icon as a decorative tile. In this case the component names the item undefined: undefined - add an explicit aria-label on the host to describe the tile to screen-reader users. The component keeps it at first render but writes its own name back at its next re-render (for example when a user preference changes).

<mds-kpi>
  <mds-kpi-item
    icon="mi/baseline/star"
    aria-label="Valutazione eccellente"
  ></mds-kpi-item>
</mds-kpi>

Styling Customization

Tune icon color, text-area background, and animation timing through the documented --mds-kpi-item-* CSS custom properties. Set them on the host or a parent selector; use the semantic color roles via rgb(var(--magma-<role>)) (agents/color.md) so dark mode keeps working.

.highlight-kpi mds-kpi-item {
  --mds-kpi-item-icon-color: rgb(var(--magma-success-emphasis));
  --mds-kpi-item-info-background: rgb(var(--magma-surface-overlay));
  --mds-kpi-item-text-animation-speed: 0.08;
  --mds-kpi-item-text-animation-placeholder-char: "0";
}

Targeting Shadow Parts for Deep Customization

When the CSS custom properties are insufficient, target the three documented shadow parts: icon-container, icon, and content. Reserve this for exceptional cases - prefer --mds-kpi-item-* vars whenever they cover your need.

mds-kpi-item::part(icon-container) {
  background-color: rgb(var(--magma-accent-surface));
  border-radius: var(--magma-radius-2xl);
}

mds-kpi-item::part(icon) {
  fill: rgb(var(--magma-accent-fg));
}