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

Body Text via Default Slot

The canonical form for body copy. Slot a plain text string; typography defaults to 'detail', which renders a <p> element with the detail style.

<mds-text>Inserisci il testo del messaggio nel campo sottostante.</mds-text>

Choosing a Typography Role

Set typography to match the semantic role. The component resolves the correct HTML element automatically - h1-h6 emit heading elements, paragraph/detail emit <p>, label/option emit <label>, snippet/hack emit <code>, tip and action emit <div> and <span> respectively.

<mds-text typography="h1">Benvenuto nel portale</mds-text>
<mds-text typography="h2">Impostazioni account</mds-text>
<mds-text typography="paragraph">Questo e' il corpo principale della pagina.</mds-text>
<mds-text typography="caption">Nota: i campi obbligatori sono contrassegnati con *</mds-text>
<mds-text typography="label">Nome utente</mds-text>
<mds-text typography="tip">Usa almeno 8 caratteri</mds-text>

Text via text Prop

Use the text prop when the string comes from a JavaScript expression or data binding. This is also required for the yugop animation (see below) since the animation watches the prop value.

<mds-text typography="detail" text="Ultimo accesso: 3 giugno 2026"></mds-text>

Reading Variant

Apply variant="read" to paragraph, detail, or caption when rendering long-form editorial content. The reading variant keeps the same sizes but switches to the serif reading font (lighter for paragraph and detail), optimized for sustained reading.

<mds-text typography="paragraph" variant="read">
  Il regolamento definisce le modalita' di accesso ai servizi digitali
  dell'amministrazione pubblica, in conformita' con le vigenti normative europee.
</mds-text>

<mds-text typography="detail" variant="read">
  Fonte: Gazzetta Ufficiale, serie generale n. 128 del 4 giugno 2026.
</mds-text>

Monospaced Code Styles

Use typography="snippet" for inline code values or short terminal output. Use typography="hack" for a smaller monospaced size suited to code-dense interfaces.

<mds-text typography="snippet">SELECT * FROM utenti WHERE attivo = true;</mds-text>
<mds-text typography="hack">npm install @maggioli-design-system/magma</mds-text>

Overriding the Rendered Tag

tag is an escape hatch to pin a specific HTML element when the typography default is semantically wrong - for example, rendering a visually large heading as a <span> for a non-heading context, or marking inline text as <strong> or <em> without changing the visual scale.

<!-- Visually h2 scale but not a landmark heading -->
<mds-text typography="h2" tag="span">Sezione in evidenza</mds-text>

<!-- Emphasized inline detail without changing scale -->
<mds-text typography="detail" tag="strong">Attenzione: questa operazione e' irreversibile.</mds-text>

<!-- Marked text using caption scale -->
<mds-text typography="caption" tag="mark">Modificato il 3 giugno 2026</mds-text>

Single-Line Truncation

Use truncate="word" to clamp text to a single line with an ellipsis when layout space is constrained, for example inside a table cell or card header.

<div style="width: 200px;">
  <mds-text typography="detail" truncate="word">
    Titolo molto lungo che supera la larghezza disponibile del contenitore
  </mds-text>
</div>

Multi-Line Clamp

Use truncate="all" to clamp text to a fixed number of lines. Control the number of visible lines via --mds-text-line-clamp (default 3).

<mds-text typography="paragraph" truncate="all" style="--mds-text-line-clamp: 2;">
  Questo paragrafo mostra solo le prime due righe di testo, troncando il resto
  con i puntini di sospensione indipendentemente dai caratteri di confine.
</mds-text>

Animated Character Reveal

Set animation="yugop" together with the text prop to run a randomized character-decode reveal each time text changes; the initial value is rendered without animation. Tune the speed via --mds-text-animation-speed.

<mds-text
  typography="h3"
  animation="yugop"
  text="Benvenuto nel sistema"
  style="--mds-text-animation-speed: 1;"
></mds-text>

Custom Text Selection Colors

Override the default selection highlight via --mds-text-selection-background and --mds-text-selection-color. Use Magma color tokens inside rgb() so dark mode keeps working.

.articolo-in-evidenza mds-text {
  --mds-text-selection-background: rgb(var(--label-orange-09));
  --mds-text-selection-color: rgb(var(--label-orange-01));
}

Custom Line-Clamp Count

Set --mds-text-line-clamp on the component host (or a parent selector) to vary the clamp depth per context without duplicating attributes.

.abstract mds-text {
  --mds-text-line-clamp: 4;
}

.anteprima mds-text {
  --mds-text-line-clamp: 2;
}