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

The simplest form: set name for form participation and placeholder for a visual hint. Wrap the component in mds-input-field to add a visible label and associated tip.

<mds-input
  name="cognome"
  placeholder="Inserisci il tuo cognome"
></mds-input>

Required Field with tip Helper Text

Use required to validate that the field is not empty and tip to explain the constraint. The component surfaces a top-tip when focused and drives variant to 'error' or 'success' on blur. When the field collects the user’s own data, set the matching autocomplete token (email, given-name, tel, …) so browsers can identify its purpose (WCAG 2.1 SC 1.3.5) and offer autofill; without it the component default autocomplete="off" applies.

<mds-input
  name="email"
  type="email"
  autocomplete="email"
  placeholder="nome@esempio.it"
  required
  tip="Inserisci un indirizzo email valido"
></mds-input>

Textarea for Multi-line Content

Set type="textarea" to render a <textarea> instead of a single-line <input>. Use the --mds-input-textarea-* custom properties to control height and resize behaviour.

<mds-input
  name="descrizione"
  type="textarea"
  placeholder="Descrivi il problema..."
  maxlength="500"
></mds-input>

Character Counter via maxlength

When maxlength is set the component renders a live current / max counter below the field. The counter shifts through fullness variants as the limit approaches. A value of 0 or less is treated as unset.

<mds-input
  name="titolo"
  placeholder="Titolo dell'articolo"
  maxlength="120"
></mds-input>

Numeric Input with Steppers

Set type="number" to enable built-in increment/decrement buttons. Use controlsLayout to choose between stacked ('vertical', default) and split ('horizontal') placement, and controlsIcon to pick arrow vs. plus/minus glyphs. Use min, max, and step to constrain the legal range.

<!-- Stacked (default) - arrow glyphs -->
<mds-input
  name="quantita"
  type="number"
  min="1"
  max="99"
  step="1"
  placeholder="1"
></mds-input>

<!-- Horizontal split - arithmetic glyphs -->
<mds-input
  name="quantita"
  type="number"
  min="0"
  max="100"
  controls-layout="horizontal"
  controls-icon="arithmetic"
  placeholder="0"
></mds-input>

Password Input

Set type="password" to render a masked field with a built-in visibility toggle. The component renders a custom dot-mask overlay and a show/hide button - no extra wiring is needed. Always set autocomplete to new-password (sign-up, password change) or current-password (login): the component default is autocomplete="off", which browsers and password managers ignore on credential fields, but the explicit token is what lets them pair the password with its username field and fill or generate the right value.

<mds-input
  name="password"
  type="password"
  autocomplete="new-password"
  placeholder="Scegli una password"
  required
></mds-input>

Login Form

Pair a username field carrying autocomplete="username" with a password field carrying autocomplete="current-password" inside a <form>, and submit through <mds-button type="submit">. The native fields live in the Shadow DOM of each <mds-input>: among the password managers tested, Bitwarden, LastPass, Chrome and Edge detect and fill them, Firefox’s built-in manager and KeePassXC-Browser do not (they only look at the light DOM).

<form action="/login" method="post">
  <mds-input-field label="Email">
    <mds-input name="username" type="email" autocomplete="username" required></mds-input>
  </mds-input-field>
  <mds-input-field label="Password">
    <mds-input name="password" type="password" autocomplete="current-password" required></mds-input>
  </mds-input-field>

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

Italian-Specific Masked Types

type="cf" installs the codice fiscale format and length validators and type="isbn" a checksum validator. type="piva" accepts 11 digits whose last one is the check digit, without the IT prefix or spaces, and type="cc" 13 to 19 digits, in groups split by spaces or dashes, that pass the Luhn check of card numbers. A value that breaks the format stops the submit of the form. No type applies a keyboard mask.

<mds-input name="codice_fiscale" type="cf" placeholder="RSSMRA80A01H501Z"></mds-input>
<mds-input name="partita_iva"    type="piva" placeholder="01234567890"></mds-input>

Search Input with Datalist

Use type="search" combined with the datalist prop to offer autocomplete suggestions from a fixed list. The list is rendered inside the shadow DOM and wired automatically.

<mds-input
  name="comune"
  type="search"
  placeholder="Cerca comune..."
></mds-input>

// Pass suggestions as a JavaScript array
document.querySelector('mds-input').datalist = ['Roma', 'Milano', 'Napoli', 'Torino'];

Icon Decoration

The icon prop renders an SVG slug from the Magma icon library at the leading edge of the field. The icon is suppressed while await is active and the spinner takes its place.

<mds-input
  name="cerca"
  type="search"
  icon="mi/baseline/search"
  placeholder="Cerca..."
></mds-input>

AI-Assisted Field

Set variant="ai" to signal an AI-powered field. When no icon prop is present, the component auto-assigns the AI chatbot icon.

<mds-input
  name="prompt"
  type="text"
  variant="ai"
  placeholder="Chiedi qualcosa all'assistente..."
></mds-input>

Async Loading via await

Set the await boolean attribute while an async operation (e.g. a lookup) is in flight. The component renders an inline spinner in place of the icon. Remove the attribute when done - do not set await="false".

<mds-input name="codice" placeholder="Verifica in corso..." await></mds-input>

Speech-to-Text Dictation

Set the mic boolean attribute to render a dictation button. Starting a dictation clears the current value and writes the recognized speech in its place; the component emits mdsInputSpeechEnd when the user stops the dictation. If the Web Speech API is unavailable the button switches to an error state and the value is kept.

<mds-input
  name="note_vocali"
  type="text"
  mic
  placeholder="Parla o scrivi..."
></mds-input>

Listening to Events

Listen for mdsInputChange instead of native input or change: change does not cross the shadow boundary, and input reports only typing, not the values set by the steppers, the dictation or a script.

document.querySelector('mds-input').addEventListener('mdsInputChange', (e) => {
  console.log(e.detail.value);
});

document.querySelector('mds-input').addEventListener('mdsInputValidation', (e) => {
  console.log('valido:', e.detail);
});

Form Participation

<mds-input> is form-associated. It submits natively inside a <form>; set name so the value is included in form data. Its validation is reported to the form too: an empty required field, or one that breaks another rule, stops the submit like a native input and shows the error. Add novalidate to the <form> when your own code validates on submit. A reset brings every field back to its value at load and to its pristine look.

<form action="/salva" method="post">
  <mds-input name="nome"    type="text"  placeholder="Nome"   required></mds-input>
  <mds-input name="cognome" type="text"  placeholder="Cognome" required></mds-input>
  <mds-input name="email"   type="email" placeholder="Email"   required></mds-input>

  <mds-button type="submit" label="Invia" variant="primary" tone="strong"></mds-button>
  <mds-button type="reset"  label="Annulla" variant="dark" tone="outline"></mds-button>
</form>

Read-Only Display

Use readonly when the value should be visible but not editable. A persistent top tip describes the state, and the field text is auto-selected on focus for easy copying.

<mds-input
  name="codice_riferimento"
  value="REF-2024-00123"
  readonly
></mds-input>

Styling Customization

Style the input only through its documented --mds-input-* CSS custom properties. Set them on the host or a parent selector. Use the semantic color roles via rgb(var(--magma-<role>)) so dark mode and high-contrast modes keep working.

.search-bar mds-input {
  --mds-input-background: rgb(var(--magma-wash-base));
  --mds-input-placeholder-default-color: rgb(var(--magma-text-disabled));
  --mds-input-icon-color: rgb(var(--magma-accent-fg));
}

/* Textarea: fixed height, allow resize */
.notes-area mds-input {
  --mds-input-textarea-min-height: 8rem;
  --mds-input-textarea-max-height: 24rem;
  --mds-input-textarea-resize: vertical;
}

Sizing a Field to the Controls Next to It

Give the fields of a row the size of the buttons beside them, so they share one height: sm 28px, md 36px, lg 48px (default), the sizes of <mds-button>. <mds-input-select>, <mds-input-date> and <mds-input-date-range> take the same values.

<div class="flex items-center gap-200">
  <mds-input size="md" type="search" icon="mi/baseline/search" placeholder="Cerca"></mds-input>
  <mds-input-select size="md" placeholder="Stato">
    <option value="open">Aperte</option>
    <option value="closed">Chiuse</option>
  </mds-input-select>
  <mds-button size="md" label="Filtra"></mds-button>
</div>