Correct and idiomatic ways to use the <mds-label> 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 Label via label Prop

The canonical form. Use the label prop for the text; it is the only way to set visible content because the component renders no <slot> element.

<mds-label label="Categoria"></mds-label>

Decorative Color via variant

Pick from the twelve label palette colors for neutral, decorative tags. Default is sky; change only when the color carries meaning to the user.

<mds-label label="Ambiente" variant="green"></mds-label>
<mds-label label="Priorita'" variant="orange"></mds-label>
<mds-label label="Archivio" variant="violet"></mds-label>
<mds-label label="Bozza" variant="sky"></mds-label>

Status Variant for Outcome Communication

Use a status variant when the label communicates a system outcome or validation state, not just a decorative category.

<mds-label label="Approvato" variant="success"></mds-label>
<mds-label label="In attesa" variant="warning"></mds-label>
<mds-label label="Rifiutato" variant="error"></mds-label>
<mds-label label="Informazione" variant="info"></mds-label>

Tone for Emphasis

Pair tone="strong" for higher-contrast situations; the default weak is lighter and suits most inline contexts.

<!-- Default: subtle tinted background -->
<mds-label label="Etichetta" variant="blue" tone="weak"></mds-label>

<!-- Higher contrast: solid background -->
<mds-label label="Etichetta" variant="blue" tone="strong"></mds-label>

Deletable Label with mdsLabelDelete Event

Set deletable to render the trailing close button. Listen to mdsLabelDelete to remove the label from your model; the close button stops event propagation so clicks do not reach a surrounding interactive container.

<mds-label label="Tag rimovibile" variant="purple" deletable></mds-label>

document.querySelector('mds-label').addEventListener('mdsLabelDelete', () => {
  // rimuovi il tag dal modello
});

Truncation Control via truncate

Use truncate="word" (default) to keep the text on one line, cut with an ellipsis. Use truncate="none" to allow multiline wrapping inside a constrained container.

<!-- Single-line truncation (default) -->
<mds-label
  label="Testo molto lungo che supera il limite"
  truncate="word"
  variant="lime"
  class="w-3200"
></mds-label>

<!-- Multiline inside a narrow container -->
<mds-label
  label="Testo molto lungo che supera il limite"
  truncate="none"
  variant="lime"
  class="w-3200"
></mds-label>

Typography Scale

Choose typography to match the surrounding text hierarchy. The default caption suits most label contexts; use detail (larger) next to body-size text and tip (smaller) only when the label sits alongside even smaller text.

<mds-label label="Caption (default)" variant="aqua" typography="caption"></mds-label>
<mds-label label="Detail" variant="aqua" typography="detail"></mds-label>
<mds-label label="Tip" variant="aqua" typography="tip"></mds-label>

Styling Customization

Style the label only through its documented --mds-label-* CSS custom properties. Set them on the host or a parent selector; use Magma color tokens via rgb(var(--<token>)) so dark mode and high-contrast modes keep working.

.categoria-speciale mds-label {
  --mds-label-background: rgb(var(--label-orchid-08));
  --mds-label-color: rgb(var(--label-orchid-02));
  --mds-label-button-background: rgb(var(--label-orchid-07));
  --mds-label-button-icon-color: rgb(var(--label-orchid-03));
}