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

Required-Field Hint

The most common use. Place one <mds-input-tip-item variant="required"> inside the parent <mds-input-tip> to signal that the field is mandatory. The localized label (“Required” / “Obbligatorio” / …) comes from the component’s own i18n dictionary - do not slot text.

<mds-input-tip active>
  <mds-input-tip-item variant="required" expanded></mds-input-tip-item>
</mds-input-tip>

Required Field Satisfied (Success State)

When the required condition is met, switch to variant="required-success". The text label is replaced by a checkmark icon - no slot is needed or expected.

<mds-input-tip active>
  <mds-input-tip-item variant="required-success" expanded></mds-input-tip-item>
</mds-input-tip>

Read-Only and Disabled State Notices

Use variant="readonly" or variant="disabled" to communicate field-state context. Both are self-labeled from the i18n dictionary and ignore any slotted content.

<!-- Campo in sola lettura -->
<mds-input-tip active>
  <mds-input-tip-item variant="readonly" expanded></mds-input-tip-item>
</mds-input-tip>

<!-- Campo disabilitato -->
<mds-input-tip active>
  <mds-input-tip-item variant="disabled" expanded></mds-input-tip-item>
</mds-input-tip>

Arbitrary Hint Text via variant="text"

Use variant="text" when you need to show a free-form helper message. Slot the text string directly; no nested HTML is accepted.

<mds-input-tip active>
  <mds-input-tip-item variant="text" expanded>Inserisci il tuo nome completo</mds-input-tip-item>
</mds-input-tip>

Character-Count Feedback

The count-* variants express how full a character-limited field is. The parent input computes the label text and slots it in; you choose the variant that matches the fill stage.

<mds-input-tip active>
  <!-- Campo vuoto -->
  <mds-input-tip-item variant="count-empty" expanded>0 / 100</mds-input-tip-item>

  <!-- In corso, entro i limiti -->
  <mds-input-tip-item variant="count-incomplete" expanded>42 / 100</mds-input-tip-item>

  <!-- Vicino al limite -->
  <mds-input-tip-item variant="count-almost" expanded>80 / 100</mds-input-tip-item>

  <!-- Quasi al limite -->
  <mds-input-tip-item variant="count-almost-full" expanded>95 / 100</mds-input-tip-item>

  <!-- Limite raggiunto -->
  <mds-input-tip-item variant="count-full" expanded>100 / 100</mds-input-tip-item>
</mds-input-tip>

Toggling Visibility with expanded

The expanded attribute controls the reveal animation. Drive it from the parent’s logic - for example, expand the required hint only while the field is focused. Collapsed, the item shrinks to a small colored dot without text.

<!-- Espanso: campo focalizzato -->
<mds-input-tip active>
  <mds-input-tip-item variant="required" expanded></mds-input-tip-item>
</mds-input-tip>

<!-- Compresso: campo non focalizzato (rimuovere l'attributo, non impostarlo a false) -->
<mds-input-tip>
  <mds-input-tip-item variant="required"></mds-input-tip-item>
</mds-input-tip>

Styling Customization

Override the visual appearance only through the three documented CSS custom properties. Set them on the host element or a parent selector; use the semantic color roles via rgb(var(--magma-<role>)) (agents/color.md) so dark mode keeps working.

.campo-personalizzato mds-input-tip-item {
  --mds-input-tip-item-background: rgb(var(--magma-accent-emphasis));
  --mds-input-tip-item-color: rgb(var(--magma-accent-on-emphasis));
  --mds-input-tip-item-icon-color: rgb(var(--magma-accent-on-emphasis));
}