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

Basic Inline Help

The canonical form. Drop <mds-help> inline next to a label or piece of text and slot in a plain string explaining the concept. The tooltip appears on hover of the help icon (the icon takes no keyboard focus).

<p>
  Periodo di fatturazione
  <mds-help>Il ciclo di fatturazione inizia il primo giorno del mese e termina l'ultimo.</mds-help>
</p>

Placement Preference

Use the placement prop to suggest a preferred side for the tooltip. The default is top; change it when the element sits near a viewport edge.

<!-- Default: tooltip above the icon -->
<mds-help placement="top">Inserire il codice fiscale a 16 caratteri.</mds-help>

<!-- Tooltip to the right, useful for left-aligned form labels -->
<mds-help placement="right">Il campo e' obbligatorio per la registrazione.</mds-help>

<!-- Tooltip below, e.g. inside a sticky header bar -->
<mds-help placement="bottom">Clicca per espandere il pannello dei filtri.</mds-help>

Disabling Auto-Placement

Auto-placement is enabled by default and overrides placement when space is constrained. Add disable-auto-placement only when you need the tooltip pinned strictly to one side - for example in a fixed overlay where you control the available space.

<!-- Add disable-auto-placement to pin the tooltip to placement="bottom" -->
<mds-help placement="bottom" disable-auto-placement>
  Questa descrizione deve sempre apparire in basso.
</mds-help>

Custom Icon

Override the default question-mark glyph with any slug from the Magma icon library by setting the icon prop. Use this to match a specific visual context - for example a warning glyph when the help text explains a potentially destructive action.

<mds-help icon="mi/baseline/info">
  Questa operazione puo' richiedere alcuni minuti.
</mds-help>

<mds-help icon="mi/baseline/warning">
  Attenzione: la modifica sara' applicata a tutti i documenti selezionati.
</mds-help>

Tooltip Width Customization

Control the tooltip dimensions with --mds-help-tooltip-width, --mds-help-tooltip-min-width, and --mds-help-tooltip-max-width. Useful when the help text is very short (narrow the tooltip) or contains several sentences (widen it).

/* Wider tooltip for a multi-sentence explanation */
.configurazione-avanzata mds-help {
  --mds-help-tooltip-max-width: 480px;
  --mds-help-tooltip-min-width: 300px;
}

/* Narrow tooltip for a short label */
.campo-codice mds-help {
  --mds-help-tooltip-max-width: 180px;
  --mds-help-tooltip-min-width: 120px;
}

Reveal Delay Customization

Increase --mds-help-tooltip-delay to prevent accidental tooltip flicker when users move their pointer across a dense form, or decrease it for touch-primary interfaces where hover is not applicable.

/* Slower reveal for dense data tables */
.tabella-dati mds-help {
  --mds-help-tooltip-delay: 0.6s;
}

/* Faster reveal in a step-by-step wizard */
.wizard-step mds-help {
  --mds-help-tooltip-delay: 0.1s;
}

Icon Part Customization

Tint the help icon to match a surrounding context using the documented ::part(icon) surface. Keep using the semantic color roles so dark mode and high-contrast modes continue to work.

/* Match the icon color to a warning banner context */
.banner-warning mds-help::part(icon) {
  fill: rgb(var(--magma-warning-text-default));
}