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

Toggle Switch with a Text Label

The canonical form. Slot a plain text string as the visible label. The component collapses the label region automatically when the slot is empty.

<mds-input-switch name="notifiche" value="1">Notifiche via e-mail</mds-input-switch>

Pre-selected and Disabled States

Use checked to pre-select the control on load. Use disabled to block interaction. Both are boolean attributes - remove them to turn them off; never write checked="false" or disabled="false".

<!-- Pre-selected -->
<mds-input-switch name="newsletter" value="1" checked>Iscrizione alla newsletter</mds-input-switch>

<!-- Disabled and unchecked -->
<mds-input-switch name="sms" value="1" disabled>Notifiche via SMS (non disponibili)</mds-input-switch>

<!-- Disabled and checked -->
<mds-input-switch name="email" value="1" checked disabled>Notifiche via e-mail (obbligatorio)</mds-input-switch>

Explicit Icon Mode

Add explicit to surface a check/remove glyph inside the toggle knob. This makes the on/off state readable without relying on color alone, which is required in high-contrast contexts. Only effective when type="switch".

<mds-input-switch name="modalita" value="1" explicit>Modalita scura</mds-input-switch>
<mds-input-switch name="animazioni" value="1" explicit checked>Animazioni ridotte</mds-input-switch>

Sizing the Toggle

Use the size prop to scale the switch knob. Sizing only applies to type="switch".

<mds-input-switch name="sm" value="1" size="sm">Piccolo</mds-input-switch>
<mds-input-switch name="md" value="1" size="md">Medio (predefinito)</mds-input-switch>
<mds-input-switch name="lg" value="1" size="lg">Grande</mds-input-switch>

Checkbox Type

Set type="checkbox" for multi-select use cases. The component renders the standard checkbox glyph set; indeterminate shows the partial-selection glyph, which is meaningful only for this type.

<!-- Basic checkboxes -->
<mds-input-switch type="checkbox" name="opt" value="a">Opzione A</mds-input-switch>
<mds-input-switch type="checkbox" name="opt" value="b" checked>Opzione B</mds-input-switch>

<!-- Indeterminate (parent of a mixed selection) -->
<mds-input-switch type="checkbox" name="tutti" value="all" indeterminate>Seleziona tutto</mds-input-switch>

Radio Group

Set type="radio" and share the same name across instances. Checking one automatically unchecks the others with the same name in the same form, and the form submits the value of the checked one.

<mds-input-switch type="radio" name="piano" value="base">Piano base</mds-input-switch>
<mds-input-switch type="radio" name="piano" value="pro" checked>Piano Pro</mds-input-switch>
<mds-input-switch type="radio" name="piano" value="enterprise">Piano Enterprise</mds-input-switch>

Form Participation

<mds-input-switch> is form-associated. The form receives value when checked; if unchecked, no value is submitted. A form reset brings back the checked state each switch had at load.

<form action="/preferenze" method="post">
  <mds-input-switch name="notifiche" value="attivo" checked>Notifiche push</mds-input-switch>
  <mds-input-switch name="newsletter" value="attivo">Newsletter settimanale</mds-input-switch>
  <mds-button type="submit" label="Salva preferenze" variant="primary" tone="strong"></mds-button>
</form>

Listening to Changes

Listen for the mdsInputSwitchChange event - it carries { name, checked, value } in event.detail. Do not listen for the native change event; it does not bubble out of Shadow DOM reliably.

<mds-input-switch id="toggle" name="tema" value="scuro">Tema scuro</mds-input-switch>

<script>
  document.querySelector('#toggle').addEventListener('mdsInputSwitchChange', (e) => {
    console.log(e.detail.name, e.detail.checked, e.detail.value);
  });
</script>

Custom Checked Icon (Checkbox / Radio)

Set icon to any slug from the Magma icon library to override the default checked glyph for type="checkbox" or type="radio". Leave icon empty to use the built-in glyph.

<mds-input-switch type="checkbox" name="preferito" value="1" icon="mi/baseline/star" checked>
  Segna come preferito
</mds-input-switch>

Typography Customization of the Label

typography and variant style the slotted text label and map to the shared typography ladder - not the tone/variant system.

<mds-input-switch name="opzione" value="1" typography="caption">Testo piccolo</mds-input-switch>
<mds-input-switch name="lettura" value="1" typography="paragraph" variant="read">Testo di lettura</mds-input-switch>

CSS Custom Property Customization

Style the switch only through the documented --mds-input-switch-* 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.

.settings-panel mds-input-switch {
  --mds-input-switch-box-color-enabled-checked: rgb(var(--magma-success-emphasis));
  --mds-input-switch-toggle-color-enabled-checked: rgb(var(--magma-success-on-emphasis));
  --mds-input-switch-duration: 200ms;
  --mds-input-switch-toggle-size: var(--mds-input-switch-toggle-size-lg);
}