Correct and idiomatic ways to use the <mds-input-field> 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 Labeled Input

The canonical form. Wrap mds-input in <mds-input-field> and set label for the visible field caption. The <mds-input> must be the first slotted element: the field wires validation to it, and with an empty slot it only logs a console warning.

<mds-input-field label="Nome e cognome">
  <mds-input name="fullName" placeholder="Es: Mario Rossi"></mds-input>
</mds-input-field>

Input with a Static Helper Message

Set message to show a persistent hint below the control. The message disappears once the slotted input emits its first mdsInputValidation event, so use this only for pre-validation guidance.

<mds-input-field label="Codice fiscale" message="16 caratteri alfanumerici">
  <mds-input name="cf" type="cf" placeholder="Es: MRCRSS83B21D704L"></mds-input>
</mds-input-field>

Validation-Driven State

When <mds-input> carries validation rules (e.g. required, type="cf", or pattern), <mds-input-field> listens for mdsInputValidation and automatically sets variant to 'error' (showing joined error messages) or 'success' (clearing the message). No event wiring is needed - just add the validation attributes to the slotted input.

<mds-input-field label="Indirizzo email">
  <mds-input name="email" type="email" required placeholder="Es: mario@esempio.it"></mds-input>
</mds-input-field>

Explicit Variant for Initial Status

If the field must start in a known non-default state - for example a server-side validation result rendered on page load - set variant directly. The validation cycle overwrites it at the first mdsInputValidation of the slotted input, which an <mds-input> emits on blur only when it has validation rules.

<!-- Server returned an error before page load -->
<mds-input-field
  label="Username"
  variant="error"
  message="Username gia in uso"
>
  <mds-input name="username" value="mario.rossi"></mds-input>
</mds-input-field>

Field with an Action Button

The default slot accepts multiple elements. The first child grows to fill the available width; subsequent children shrink to their natural size. Use this to pair an input with a companion mds-button.

<mds-input-field label="Cerca per nome">
  <mds-input name="query" placeholder="Es: Mario Rossi"></mds-input>
  <mds-button icon="mi/baseline/search" size="lg" aria-label="Cerca"></mds-button>
</mds-input-field>

Inside a Form

The slotted <mds-input> is itself form-associated and submits under its own name. Place the field inside a <form> with a submit button; the field requires no extra wiring.

<form action="/registrazione" method="post">
  <mds-input-field label="Nome">
    <mds-input name="firstName" required placeholder="Es: Mario"></mds-input>
  </mds-input-field>

  <mds-input-field label="Cognome">
    <mds-input name="lastName" required placeholder="Es: Rossi"></mds-input>
  </mds-input-field>

  <mds-button type="submit" label="Registrati" variant="primary" tone="strong"></mds-button>
</form>

Styling Customization

Adjust the message area colors through the two documented --mds-input-field-* CSS custom properties. Use the semantic color roles via rgb(var(--magma-<role>)) (agents/color.md) so dark mode and high-contrast modes keep working.

.field-highlight mds-input-field {
  --mds-input-field-message-color: rgb(var(--magma-accent-fg));
  --mds-input-field-message-background: rgb(var(--magma-accent-surface));
}