Checkbox
Turns one option on or off.
<mm-checkbox name="notify" value="failures" label="Notify me when this pipeline fails" checked></mm-checkbox>
Guidance
Checkboxes turn one option on or off: "Notify me when this pipeline fails", "Include
deprecated assets". The label sits beside the 16px box and is clickable, with an optional
description line under it. indeterminate shows a dash for a parent whose children are mixed.
The checked box is filled with ink (mm-text) and carries an mm-on-inverse tick. It is not
burnt sienna: the guidelines reserves burnt sienna for the primary action, links, the active tab and the
current selection, at most once per row. A settings list can hold a dozen ticked boxes, which
would spend the accent many times over and read as a row of selections. Ink keeps the state
unmistakable at 17:1 while leaving the accent for what it marks.
Keyboard: Space toggles (https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/). The control is a native checkbox inside the shadow root, so it is announced as mixed when indeterminate.
Form-associated: submits value (default on) under name only while checked, as a native
checkbox does. required means it must be ticked. The checked attribute is the default the
form resets to.
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
checked | checked | boolean | false | |
indeterminate | indeterminate | boolean | false | Shows a dash for a mixed state; cleared when the user toggles. |
value | value | string | 'on' | Submitted under name while checked. Default on. |
description | description | string | '' | A second line under 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 |
|---|---|
click() | Toggles like a click. |
formResetCallback() | Restore the initial value when the owning form resets. |
Events
| Event | Detail | Description |
|---|---|---|
mm-input | CustomEvent<MmCheckedDetail> | When the box is toggled. |
mm-change | CustomEvent<MmCheckedDetail> | When the box is toggled. |
input | InputEvent | Native, composed; when the box is toggled. |
change | Event | Native, re-dispatched on the host when the box is toggled. |
CSS parts
| Part | Description |
|---|---|
control | The native checkbox drawn as the box. |
label | The label beside the box. |
description | The description line. |
help | The help line. |
error | The error line. |
Examples
Every state of mm-checkbox in Storybook, with keyboard and screen reader tests.