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

Basic Spinner - Hidden by Default

The component is invisible and animation-paused until running is set. Render it into the DOM early and toggle running when a request starts; removing the attribute (or setting the prop to undefined) hides it again when done.

<!-- Spinner hidden - no running attribute -->
<mds-spinner></mds-spinner>

<!-- Spinner visible and animating -->
<mds-spinner running></mds-spinner>

Inline Loading Indicator

Place the spinner next to a label to signal that a section is loading. The spinner is painted in the accent color (--magma-accent-fg) by default; set color on the host to match the surrounding text instead.

<div class="loading-row">
  <mds-spinner running></mds-spinner>
  <span>Caricamento dati in corso...</span>
</div>

Full-Page or Overlay Loading State

Centre the spinner over a region with a wrapper. Drive running programmatically - set it when the async operation starts, remove it when done.

<div class="overlay">
  <mds-spinner running></mds-spinner>
</div>

.overlay {
  align-items: center;
  display: flex;
  inset: 0;
  justify-content: center;
  position: absolute;
}

Inside mds-button (via await)

mds-button manages its own internal <mds-spinner> automatically through its await prop. Do not add a separate <mds-spinner> next to a button - use await on the button itself.

<!-- While an async operation is in flight -->
<mds-button label="Salvataggio in corso..." await variant="primary" tone="strong"></mds-button>

Controlling Animation Speed

Use the --mds-spinner-duration CSS custom property to tune the rotation speed. Set it on the host element - shorter values spin faster, longer values spin slower. The component slows the spinner down under the OS reduced-motion setting by changing this same property, so an override on the host also replaces that slowdown: keep it for brand or context-specific adjustments only.

.fast-indicator mds-spinner {
  --mds-spinner-duration: 0.4s;
}

.slow-indicator mds-spinner {
  --mds-spinner-duration: 1.5s;
}

Accessible Loading Region

<mds-spinner> is purely decorative and carries no ARIA role. Announce the loading state to screen readers by adding aria-busy and aria-live on the surrounding container, not on the spinner itself.

<section aria-busy="true" aria-live="polite" aria-label="Ricerca in corso">
  <mds-spinner running></mds-spinner>
</section>

Colour Customization via CSS Color

The spinner stroke inherits color from the host, so you can recolour it without touching shadow internals. Use a semantic colour role so dark mode and high-contrast modes keep working.

.status-warning-spinner mds-spinner {
  color: rgb(var(--magma-warning-text-default));
}

<div class="status-warning-spinner">
  <mds-spinner running></mds-spinner>
</div>