2.14.0
Checkboxes afford one or more selection from a set of options.
See Forms for guidance on composing full forms.
Use when affording a binary selection.
<label class="mds-form__checkbox" for="i-accept-the-terms-and-conditions.--10373">
<input id="i-accept-the-terms-and-conditions.--10373" type="checkbox" class="mds-form__checkbox-input" />
<span class="mds-form__checkbox-visible-wrap">
<span class="mds-form__checkbox-visual">
<svg class="mds-icon mds-form__checkbox-checked-icon" aria-hidden="true">
<use xlink:href="/icons/mds.svg#check--s">
</use>
</svg>
<svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
<use xlink:href="/icons/mds.svg#minus--s">
</use>
</svg>
</span>
<span class="mds-form__checkbox-text"> I accept the terms and conditions. </span>
</span>
</label>
<mds-checkbox>I accept the terms and conditions.</mds-checkbox>
<label class="mds-form__checkbox mds-form__checkbox--disabled" for="i-accept-the-terms-and-conditions.--40020">
<input id="i-accept-the-terms-and-conditions.--40020" type="checkbox" class="mds-form__checkbox-input" disabled />
<span class="mds-form__checkbox-visible-wrap">
<span class="mds-form__checkbox-visual">
<svg class="mds-icon mds-form__checkbox-checked-icon" aria-hidden="true">
<use xlink:href="/icons/mds.svg#check--s">
</use>
</svg>
<svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
<use xlink:href="/icons/mds.svg#minus--s">
</use>
</svg>
</span>
<span class="mds-form__checkbox-text"> I accept the terms and conditions. </span>
</span>
</label>
<mds-checkbox disabled>I accept the terms and conditions.</mds-checkbox>
<label class="mds-form__checkbox" for="i-accept-the-terms-and-conditions.--15155">
<input id="i-accept-the-terms-and-conditions.--15155" type="checkbox" class="mds-form__checkbox-input" checked />
<span class="mds-form__checkbox-visible-wrap">
<span class="mds-form__checkbox-visual">
<svg class="mds-icon mds-form__checkbox-checked-icon" aria-hidden="true">
<use xlink:href="/icons/mds.svg#check--s">
</use>
</svg>
<svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
<use xlink:href="/icons/mds.svg#minus--s">
</use>
</svg>
</span>
<span class="mds-form__checkbox-text"> I accept the terms and conditions. </span>
</span>
</label>
<mds-checkbox checked>I accept the terms and conditions.</mds-checkbox>
<label class="mds-form__checkbox mds-form__checkbox--disabled" for="i-accept-the-terms-and-conditions.--59978">
<input id="i-accept-the-terms-and-conditions.--59978" type="checkbox" class="mds-form__checkbox-input" checked disabled />
<span class="mds-form__checkbox-visible-wrap">
<span class="mds-form__checkbox-visual">
<svg class="mds-icon mds-form__checkbox-checked-icon" aria-hidden="true">
<use xlink:href="/icons/mds.svg#check--s">
</use>
</svg>
<svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
<use xlink:href="/icons/mds.svg#minus--s">
</use>
</svg>
</span>
<span class="mds-form__checkbox-text"> I accept the terms and conditions. </span>
</span>
</label>
<mds-checkbox checked disabled>I accept the terms and conditions.</mds-checkbox>
Use when enabling selection of an object such as a Card.
<label class="mds-form__checkbox mds-form__checkbox--hide-label" for="i-accept-the-terms-and-conditions--41038">
<input id="i-accept-the-terms-and-conditions--41038" type="checkbox" class="mds-form__checkbox-input" />
<span class="mds-form__checkbox-visible-wrap">
<span class="mds-form__checkbox-visual">
<svg class="mds-icon mds-form__checkbox-checked-icon" aria-hidden="true">
<use xlink:href="/icons/mds.svg#check--s">
</use>
</svg>
<svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
<use xlink:href="/icons/mds.svg#minus--s">
</use>
</svg>
</span>
<span class="mds-form__checkbox-text"> I accept the terms and conditions </span>
</span>
</label>
<mds-checkbox hidden-text="true">I accept the terms and conditions.</mds-checkbox>
<label>
element, even if it is hidden from the screen.Use when affording multiple selections from a set of options.
<form class="mds-form mds-form--medium-layout" method="post" action="form/processor">
<div class="mds-form__field-group">
<fieldset class="mds-form__checkbox-group" role="group">
<legend class="mds-form__checkbox-group-label"> Select statistics to view. </legend>
<label class="mds-form__checkbox" for="average--12585">
<input id="average--12585" type="checkbox" class="mds-form__checkbox-input" name="statistics-id-86382" />
<span class="mds-form__checkbox-visible-wrap">
<span class="mds-form__checkbox-visual">
<svg class="mds-icon mds-form__checkbox-checked-icon" aria-hidden="true">
<use xlink:href="/icons/mds.svg#check--s">
</use>
</svg>
<svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
<use xlink:href="/icons/mds.svg#minus--s">
</use>
</svg>
</span>
<span class="mds-form__checkbox-text"> Average </span>
</span>
</label>
<label class="mds-form__checkbox" for="minimum--44940">
<input id="minimum--44940" type="checkbox" class="mds-form__checkbox-input" name="statistics-id-86382" />
<span class="mds-form__checkbox-visible-wrap">
<span class="mds-form__checkbox-visual">
<svg class="mds-icon mds-form__checkbox-checked-icon" aria-hidden="true">
<use xlink:href="/icons/mds.svg#check--s">
</use>
</svg>
<svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
<use xlink:href="/icons/mds.svg#minus--s">
</use>
</svg>
</span>
<span class="mds-form__checkbox-text"> Minimum </span>
</span>
</label>
<label class="mds-form__checkbox" for="maximum--70495">
<input id="maximum--70495" type="checkbox" class="mds-form__checkbox-input" name="statistics-id-86382" />
<span class="mds-form__checkbox-visible-wrap">
<span class="mds-form__checkbox-visual">
<svg class="mds-icon mds-form__checkbox-checked-icon" aria-hidden="true">
<use xlink:href="/icons/mds.svg#check--s">
</use>
</svg>
<svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
<use xlink:href="/icons/mds.svg#minus--s">
</use>
</svg>
</span>
<span class="mds-form__checkbox-text"> Maximum </span>
</span>
</label>
<label class="mds-form__checkbox" for="median--284">
<input id="median--284" type="checkbox" class="mds-form__checkbox-input" name="statistics-id-86382" />
<span class="mds-form__checkbox-visible-wrap">
<span class="mds-form__checkbox-visual">
<svg class="mds-icon mds-form__checkbox-checked-icon" aria-hidden="true">
<use xlink:href="/icons/mds.svg#check--s">
</use>
</svg>
<svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
<use xlink:href="/icons/mds.svg#minus--s">
</use>
</svg>
</span>
<span class="mds-form__checkbox-text"> Median </span>
</span>
</label>
</fieldset>
</div>
</form>
<form class="mds-form mds-form--medium-layout" method="post" action="form/processor">
<div class="mds-form__field-group">
<mds-checkbox-group label="Select statistics to view.">
<mds-checkbox id="checkbox-1" value="average">Average</mds-checkbox>
<mds-checkbox id="checkbox-2" value="minimum">Minimum</mds-checkbox>
<mds-checkbox id="checkbox-3" value="maximum">Maximum</mds-checkbox>
<mds-checkbox id="checkbox-4" value="median">Median</mds-checkbox>
</mds-checkbox-group>
</div>
</form>
<form class="mds-form mds-form--medium-layout" method="post" action="form/processor">
<div class="mds-form__field-group mds-form__field-group--horizontal">
<fieldset class="mds-form__checkbox-group" role="group">
<legend class="mds-form__checkbox-group-label"> Select statistics to view. </legend>
<label class="mds-form__checkbox" for="average--90854">
<input id="average--90854" type="checkbox" class="mds-form__checkbox-input" name="statistics-id-86382" />
<span class="mds-form__checkbox-visible-wrap">
<span class="mds-form__checkbox-visual">
<svg class="mds-icon mds-form__checkbox-checked-icon" aria-hidden="true">
<use xlink:href="/icons/mds.svg#check--s">
</use>
</svg>
<svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
<use xlink:href="/icons/mds.svg#minus--s">
</use>
</svg>
</span>
<span class="mds-form__checkbox-text"> Average </span>
</span>
</label>
<label class="mds-form__checkbox" for="minimum--85354">
<input id="minimum--85354" type="checkbox" class="mds-form__checkbox-input" name="statistics-id-86382" />
<span class="mds-form__checkbox-visible-wrap">
<span class="mds-form__checkbox-visual">
<svg class="mds-icon mds-form__checkbox-checked-icon" aria-hidden="true">
<use xlink:href="/icons/mds.svg#check--s">
</use>
</svg>
<svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
<use xlink:href="/icons/mds.svg#minus--s">
</use>
</svg>
</span>
<span class="mds-form__checkbox-text"> Minimum </span>
</span>
</label>
<label class="mds-form__checkbox" for="maximum--9574">
<input id="maximum--9574" type="checkbox" class="mds-form__checkbox-input" name="statistics-id-86382" />
<span class="mds-form__checkbox-visible-wrap">
<span class="mds-form__checkbox-visual">
<svg class="mds-icon mds-form__checkbox-checked-icon" aria-hidden="true">
<use xlink:href="/icons/mds.svg#check--s">
</use>
</svg>
<svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
<use xlink:href="/icons/mds.svg#minus--s">
</use>
</svg>
</span>
<span class="mds-form__checkbox-text"> Maximum </span>
</span>
</label>
<label class="mds-form__checkbox" for="median--82045">
<input id="median--82045" type="checkbox" class="mds-form__checkbox-input" name="statistics-id-86382" />
<span class="mds-form__checkbox-visible-wrap">
<span class="mds-form__checkbox-visual">
<svg class="mds-icon mds-form__checkbox-checked-icon" aria-hidden="true">
<use xlink:href="/icons/mds.svg#check--s">
</use>
</svg>
<svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
<use xlink:href="/icons/mds.svg#minus--s">
</use>
</svg>
</span>
<span class="mds-form__checkbox-text"> Median </span>
</span>
</label>
</fieldset>
</div>
</form>
<form class="mds-form mds-form--medium-layout" method="post" action="form/processor">
<div class="mds-form__field-group mds-form__field-group--horizontal">
<mds-checkbox-group label="Select statistics to view.">
<mds-checkbox id="checkbox-1" value="average">Average</mds-checkbox>
<mds-checkbox id="checkbox-2" value="minimum">Minimum</mds-checkbox>
<mds-checkbox id="checkbox-3" value="maximum">Maximum</mds-checkbox>
<mds-checkbox id="checkbox-4" value="median">Median</mds-checkbox>
</mds-checkbox-group>
</div>
</form>
Use when affording a “Select All” option. After selecting all items, the indeterminate state is triggered once an option is deselected.
<label class="mds-form__checkbox" for="indeterminate-checkbox--82208">
<input id="indeterminate-checkbox--82208" type="checkbox" class="mds-form__checkbox-input" checked />
<span class="mds-form__checkbox-visible-wrap">
<span class="mds-form__checkbox-visual">
<svg class="mds-icon mds-form__checkbox-checked-icon" aria-hidden="true">
<use xlink:href="/icons/mds.svg#check--s">
</use>
</svg>
<svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
<use xlink:href="/icons/mds.svg#minus--s">
</use>
</svg>
</span>
<span class="mds-form__checkbox-text"> Indeterminate checkbox </span>
</span>
</label>
<!-- Something like the following Javascript would be required to set an indeterminate state on a checkbox -->
<script>
document.getElementById("indeterminate-checkbox--82208").indeterminate = true;
</script>
<mds-checkbox checked indeterminate="true">Indeterminate checkbox</mds-checkbox>
Sizing affects checkbox size and text size. The default size is medium, and you can use modifier classes or props to make the checkbox smaller or larger.
<label class="mds-form__checkbox mds-form__checkbox--small" for="small-checkbox">
<input id="small-checkbox" type="checkbox" class="mds-form__checkbox-input" />
<span class="mds-form__checkbox-visible-wrap">
<span class="mds-form__checkbox-visual">
<svg class="mds-icon mds-form__checkbox-checked-icon" aria-hidden="true">
<use xlink:href="/icons/mds.svg#check--s">
</use>
</svg>
<svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
<use xlink:href="/icons/mds.svg#minus--s">
</use>
</svg>
</span>
<span class="mds-form__checkbox-text"> Checkbox Label </span>
</span>
</label>
<br>
<label class="mds-form__checkbox mds-form__checkbox--hide-label mds-form__checkbox--small" for="small-checkbox-without-label">
<input id="small-checkbox-without-label" type="checkbox" class="mds-form__checkbox-input" />
<span class="mds-form__checkbox-visible-wrap">
<span class="mds-form__checkbox-visual">
<svg class="mds-icon mds-form__checkbox-checked-icon" aria-hidden="true">
<use xlink:href="/icons/mds.svg#check--s">
</use>
</svg>
<svg class="mds-icon mds-form__checkbox-indeterminate-icon" aria-hidden="true">
<use xlink:href="/icons/mds.svg#minus--s">
</use>
</svg>
</span>
<span class="mds-form__checkbox-text"> Checkbox Label </span>
</span>
</label>
<mds-checkbox size="small" id="small-wc-checkbox">Checkbox Label</mds-checkbox>
<br>
<mds-checkbox hidden-text="true" id="small-checkbox-wc-without-label">Checkbox Label</mds-checkbox>
mds-form__checkbox-without-label
class in conjunction with checkbox sizing modifier classes to render different sizes of the Without Label variation.:hover
and :active
styles as the primary Button when checked.
Class
|
Applies to
|
Outcome
|
---|---|---|
|
|
Adjusts styling to render a small checkbox. |
|
|
Adjusts styling to render a large checkbox. |
|
|
Hides label text, although screen readers can still access it. |
Checkboxes are comprised of two separate web components, each with a dedicated API:
<mds-checkbox>
elements to present them as a group.
Prop
|
Type
|
Validation
|
Default
|
Description
|
---|---|---|---|---|
|
Boolean |
— |
|
Sets the checked value of the checkbox. |
|
String |
— |
— |
A space-separated list of class names that will be appended to the default |
|
Boolean |
— |
|
If |
|
Boolean |
— |
|
When true, hides the checkbox's label. |
|
String |
Required |
— |
The |
|
Boolean |
— |
|
If |
|
String |
Enum: |
|
Alters the size of the checkbox. |
|
String |
Required |
— |
The checkbox label text. |
|
String |
Required |
— |
The checkbox value. |
hiddenLabel
would be written as hidden-label
.Any text passed in between <mds-checkbox></mds-checkbox>
tags will be used as the checkbox’s label. This slot can accept plain text, or a combination of text and link where appropriate. If no content is passed in via the slot and the text
prop is empty, the checkbox label content will be empty.
Setting size, checked status, and label text:
<!-- Using Props -->
<mds-checkbox size="small" text="I accept" checked></mds-checkbox>
<!-- Using Slots -->
<mds-checkbox size="small" checked> I accept </mds-checkbox>
Creating a checkbox with a hidden label:
<!-- Using Props -->
<mds-checkbox hidden-label="true" text="Portfolio 1"></mds-checkbox>
<!-- Using Slots -->
<mds-checkbox hidden-label="true"> Portfolio 1 </mds-checkbox>
Prop
|
Type
|
Validation
|
Default
|
Description
|
---|---|---|---|---|
|
String |
— |
“Please select an option.” |
Sets the checkbox group label’s required indicator |
|
String |
— |
— |
A space-separated list of class names that will be appended to the default |
|
String |
— |
— |
Checkboxes to display within the group. Can also be passed using the default slot. |
|
String |
— |
— |
The |
|
String |
Required |
— |
Label for the checkbox group. |
|
Boolean |
— |
|
If true, adds the optional indicator to the right of the label with a default text of “(Optional)”. |
|
String |
— |
“(Optional)” |
Use to override the default optional indicator text. |
|
Boolean |
— |
|
If true, adds the required field indicator to the right of the label. |
|
String |
Enum: |
|
Alters the size of the checkbox group label. |
optionalText
would be written as optional-text
.Pass two or more <mds-checkbox>
elements between the <mds-checkbox-group></mds-checkbox-group>
to set the content of the checkbox group. This slot can be overridden using the content
prop.
Creating a required checkbox group:
<!-- Using Props -->
<mds-checkbox-group required label="Choose your options." content='<mds-checkbox text="Option 1" id="checkbox-option-1" value="option-1"></mds-checkbox> <mds-checkbox text="Option 2" id="checkbox-option-2" value="option-2"></mds-checkbox>'></mds-checkbox-group>
<!-- Using Slots -->
<mds-checkbox-group required label="Choose your options.">
<mds-checkbox id="checkbox-option-1" value="option-1"> Option 1 </mds-checkbox>
<mds-checkbox id="checkbox-option-2" value="option-2"> Option 2 </mds-checkbox>
</mds-checkbox-group>
fieldset
and legend
for checkbox groups. See the form structure guidelines in the Forms composition section for more information.