Correct and idiomatic ways to use the <mds-input-select> 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 Select with Placeholder

The canonical form. Slot plain <option> elements as direct children. Set placeholder to inject a leading empty-value entry that prompts the user before a choice is made.

<mds-input-select name="categoria" placeholder="Seleziona una categoria...">
  <option value="news">Notizie</option>
  <option value="eventi">Eventi</option>
  <option value="avvisi">Avvisi</option>
</mds-input-select>

Required Select Inside a Form

Adding required enforces a non-empty submission - an empty select stops the submit like a native one - and disables the placeholder option once a valid choice exists, so users cannot revert to the empty entry. Place the component inside a <form> - it is form-associated and submits natively.

<form action="/salva" method="post">
  <mds-input-select name="regione" required placeholder="Scegli la regione...">
    <option value="lombardia">Lombardia</option>
    <option value="veneto">Veneto</option>
    <option value="toscana">Toscana</option>
  </mds-input-select>
  <mds-button type="submit" label="Invia" variant="primary" tone="strong"></mds-button>
</form>

Pre-selected Value via value

Pass value to open the component with a specific option already chosen. The matching <option> is marked selected automatically. Use default-value instead when the initial selection is set once at load and you do not need live two-way binding (notably in the React wrapper).

<!-- Live controlled value -->
<mds-input-select name="priorita" value="alta">
  <option value="bassa">Bassa</option>
  <option value="media">Media</option>
  <option value="alta">Alta</option>
</mds-input-select>

<!-- Initial seed value for React / SSR -->
<mds-input-select name="priorita" default-value="media">
  <option value="bassa">Bassa</option>
  <option value="media">Media</option>
  <option value="alta">Alta</option>
</mds-input-select>

Listening to Value Changes

Listen to mdsInputSelectChange - do not rely on the native change event, which may not bubble out of shadow DOM reliably. The event detail carries the chosen value as a string in value, and the values of every selected option in values.

<mds-input-select id="stato-pratica" name="stato" placeholder="Seleziona stato...">
  <option value="bozza">Bozza</option>
  <option value="in-lavorazione">In lavorazione</option>
  <option value="chiusa">Chiusa</option>
</mds-input-select>

<script>
  document.getElementById('stato-pratica')
    .addEventListener('mdsInputSelectChange', (event) => {
      console.log('Nuovo stato:', event.detail.value);
    });
</script>

Programmatic Value via setValue()

Use the setValue() async method when you need to change the selection from JavaScript after the component has rendered - for example when a related control resets the form state.

<mds-input-select id="provincia" name="provincia" placeholder="Seleziona provincia...">
  <option value="MI">Milano</option>
  <option value="RM">Roma</option>
  <option value="TO">Torino</option>
</mds-input-select>

<script>
  async function resetSelezione() {
    const el = document.getElementById('provincia');
    await el.setValue('MI');
  }
</script>

Disabled State

Set disabled as a boolean attribute to block interaction and remove the value from the submitted form data. A status tip is shown automatically while the component is disabled.

<mds-input-select name="tipo-contratto" disabled placeholder="Non disponibile">
  <option value="td">Tempo determinato</option>
  <option value="ti">Tempo indeterminato</option>
</mds-input-select>

Multi-select List Box

multiple switches the component to a scrollable list that allows zero or more simultaneous selections. Use rows to control how many rows are visible without scrolling (size sets the height of the field). Mark the options to preselect with selected, as in a native <select multiple>. The form submits an entry per selected option under name, and values in the mdsInputSelectChange detail lists them all; value holds only the first one, as select.value does.

<mds-input-select name="competenze" multiple rows="4">
  <option value="js" selected>JavaScript</option>
  <option value="ts" selected>TypeScript</option>
  <option value="css">CSS</option>
  <option value="html">HTML</option>
  <option value="react">React</option>
</mds-input-select>

Grouped Options via <optgroup>

The default slot also accepts <optgroup> elements. Use them to group related options under a visible label.

<mds-input-select name="comune" placeholder="Seleziona comune...">
  <optgroup label="Lombardia">
    <option value="MI">Milano</option>
    <option value="BS">Brescia</option>
  </optgroup>
  <optgroup label="Veneto">
    <option value="VE">Venezia</option>
    <option value="VR">Verona</option>
  </optgroup>
</mds-input-select>

Variant for Validation Feedback

Set variant to one of the status values (error, success, warning, info) to communicate the validation outcome visually. Use this after a form submission or inline validation, not as decorative styling.

<!-- Errore di validazione -->
<mds-input-select name="tipologia" variant="error" required placeholder="Seleziona tipologia...">
  <option value="A">Tipo A</option>
  <option value="B">Tipo B</option>
</mds-input-select>

<!-- Selezione valida confermata -->
<mds-input-select name="tipologia" variant="success" value="A">
  <option value="A">Tipo A</option>
  <option value="B">Tipo B</option>
</mds-input-select>

Styling Customization

Customize the component only through its documented --mds-input-select-* CSS custom properties. Set them on the host or a parent selector; use the semantic color roles (agents/color.md) so dark mode and high-contrast modes continue to work correctly. --mds-input-select-variant-color-rgb takes a bare RGB triplet (var(--magma-<role>), no rgb()); the other properties take a color (rgb(var(--magma-<role>))). --mds-input-select-ring is the ring at rest: on hover and focus the select draws its own 3px ring in the variant color, so the focus stays visible whatever the ring at rest, in dark mode and with more contrast too; change its color through --mds-input-select-variant-color-rgb.

.sidebar-filter mds-input-select {
  --mds-input-select-variant-color-rgb: var(--magma-accent-emphasis);
  --mds-input-select-arrow-icon-hover-color: rgb(var(--magma-accent-fg));
  --mds-input-select-arrow-icon-hover-background-color: rgb(var(--magma-accent-surface-hover));
  --mds-input-select-ring: 0 0 0 2px rgb(var(--magma-accent-emphasis) / 0.8);
}