Switch
Turns a setting on or off.
<mm-switch name="masking" label="Mask PII in query results" checked></mm-switch>
Guidance
Switches turn a setting on or off with immediate effect: "Run this pipeline on a schedule", "Mask PII in query results". Use a checkbox instead when the choice only applies after a form is saved alongside other fields.
State never relies on colour alone: when on, the track fills with ink and the thumb moves to the
end and carries a tick; when off, the track is open and the thumb is empty. Set state-label to
also print "On" or "Off" beside the label. The track is a 4px-radius control, not a pill: the
The guidelines keep full radius for avatars, status pills and filter pills.
Keyboard: Space and Enter toggle (https://www.w3.org/WAI/ARIA/apg/patterns/switch/). The control
is a native button with role="switch" and aria-checked.
Form-associated: submits value (default on) under name only while on. required means it
must be on. The checked attribute is the default the form resets to.
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
checked | checked | boolean | false | |
value | value | string | 'on' | Submitted under name while on. Default on. |
description | description | string | '' | A second line under the label. |
stateLabel | state-label | boolean | false | Also prints "On" or "Off" beside the label. |
label | label | string | '' | Field label. Rendered above the control unless hide-label, and always the accessible name. |
help | help | string | '' | Help text under the control. |
error | error | string | '' | Error text: a sentence saying what to fix. Shows the crimson border, an icon and sets aria-invalid. |
hideLabel | hide-label | boolean | false | Hides the label visually; it stays the accessible name. |
optional | optional | boolean | false | Marks the field as optional, in words. |
name | name | string | '' | Name submitted with the form. |
disabled | disabled | boolean | false | Disables the control and excludes it from submission. |
required | required | boolean | false | Requires a value before the form submits. |
form | HTMLFormElement | null | |||
validity | ValidityState | |||
validationMessage | string | |||
willValidate | boolean | |||
isDisabled | boolean | True when disabled directly or by a disabled ancestor fieldset. |
Methods
| Method | Description |
|---|---|
toggle() | Flips the switch, as a click or Space does. |
formResetCallback() | Restore the initial value when the owning form resets. |
Events
| Event | Detail | Description |
|---|---|---|
mm-input | CustomEvent<MmSwitchDetail> | When the switch is toggled. |
mm-change | CustomEvent<MmSwitchDetail> | When the switch is toggled. |
input | InputEvent | When the switch is toggled. |
change | Event | When the switch is toggled. |
CSS parts
| Part | Description |
|---|---|
control | The switch button (track). |
thumb | The moving thumb. |
label | The label beside the switch. |
description | The description line. |
help | The help line. |
error | The error line. |
Examples
Every state of mm-switch in Storybook, with keyboard and screen reader tests.