Skip to content
On this page

Checkbox

Usage

Checkboxes may be standalone, pre-checked, or indeterminate.

Three checkboxes in a row that are unselected, selected, and indeterminate

html
<md-checkbox touch-target="wrapper"></md-checkbox>
<md-checkbox touch-target="wrapper" checked></md-checkbox>
<md-checkbox touch-target="wrapper" indeterminate></md-checkbox>

Label

Associate a label with a checkbox using the <label> element.

Two checkboxes with labels

html
<label>
  <md-checkbox touch-target="wrapper"></md-checkbox>
  Checkbox one
</label>

<md-checkbox id="checkbox-two" touch-target="wrapper"></md-checkbox>
<label for="checkbox-two">Checkbox two</label>

Accessibility

Add an aria-label attribute to checkboxes without labels or checkboxes whose labels need to be more descriptive.

html
<md-checkbox aria-label="Select all checkboxes"></md-checkbox>

<label>
  <md-checkbox aria-label="Agree to terms and conditions"></md-checkbox>
  Agree
</label>

Note: checkboxes are not automatically labelled by <label> elements and always need an aria-label. See b/294081528.

Theming

Checkbox supports Material theming and can be customized in terms of color and shape.

Tokens

TokenDefault value
--md-checkbox-outline-color--md-sys-color-on-surface-variant
--md-checkbox-selected-container-color--md-sys-color-primary
--md-checkbox-selected-icon-color--md-sys-color-on-primary
--md-checkbox-container-shape2px

Example

Image of a checkbox with a different theme applied

html
<style>
  :root {
    /* System tokens */
    --md-sys-color-primary: #006a6a;
    --md-sys-color-on-primary: #ffffff;
    --md-sys-color-on-surface-variant: #3f4948;

    /* Component tokens */
    --md-checkbox-container-shape: 0px;
  }
</style>

<md-checkbox touch-target="wrapper"></md-checkbox>
<md-checkbox touch-target="wrapper" checked></md-checkbox>

API

MdCheckbox <md-checkbox>

Properties

PropertyAttributeTypeDefaultDescription
checkedcheckedbooleanfalseWhether or not the checkbox is selected.
indeterminateindeterminatebooleanfalseWhether or not the checkbox is indeterminate.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#indeterminate_state_checkboxes
requiredrequiredbooleanfalseWhen true, require the checkbox to be selected when participating in form submission.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#validation
valuevaluestring'on'The value of the checkbox that is submitted with a form when selected.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#value
disabledbooleanundefined
namestringundefined

Methods

MethodParametersReturnsDescription
formResetCallbackNonevoid
formStateRestoreCallbackstatevoid

Events

EventTypeBubblesComposedDescription
changeEventYesNoThe native change event on <input>
inputInputEventYesYesThe native input event on <input>
Checkbox has loaded