Checkbox

Checkboxes select any number of items from a set, or turn a single option on or off.

There's one type of checkbox in Material. Use this selection control when the user needs to select one or more options from a list.

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

Interactive Demo

Link to “Interactive Demo”

View interactive demo inline.

Open interactive demo in new tab.

Usage

Link to “Usage”

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

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

Label

Link to “Label”

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

Checkbox one

Checkbox two

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

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

Accessibility

Link to “Accessibility”

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

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

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

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

Theming

Link to “Theming”

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

Tokens

Link to “Tokens”

Token	Default 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-shape`	`2px`

All tokens

Example

Link to “Example”

<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>

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

API

Link to “API”

PetalCheckbox `<petal-checkbox>`

Link to “PetalCheckbox <petal-checkbox>”

Properties

Link to “Properties”

Property	Attribute	Type	Default	Description
`checked`	`checked`	`boolean`	`false`	Whether or not the checkbox is selected.
`indeterminate`	`indeterminate`	`boolean`	`false`	Whether or not the checkbox is indeterminate. https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#indeterminate_state_checkboxes
`required`	`required`	`boolean`	`false`	When 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
`value`	`value`	`string`	`'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
`name`	`name`	`string`	`undefined`	The HTML name to use in form submission.
`disabled`	`disabled`	`boolean`	`undefined`	Whether or not the element is disabled.
`form`		`HTMLFormElement`	`undefined`	The associated form element with which this element's value will submit.
`labels`		`NodeList`	`undefined`	The labels this element is associated with.
`validity`		`ValidityState`	`undefined`	Returns a ValidityState object that represents the validity states of the element. https://developer.mozilla.org/en-US/docs/Web/API/ValidityState
`validationMessage`		`string`	`undefined`	Returns a validation error message or an empty string if the element is valid. https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/validationMessage
`willValidate`		`boolean`	`undefined`	Returns whether an element will successfully validate based on forms validation rules and constraints. Disabled and readonly elements will not validate. https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/willValidate

Methods

Link to “Methods”

Method	Parameters	Returns	Description
`formResetCallback`	None	`void`
`formStateRestoreCallback`	`state`	`void`
`checkValidity`	None	`boolean`	Checks the element's constraint validation and returns true if the element is valid or false if not. If invalid, this method will dispatch an `invalid` event. https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/checkValidity
`reportValidity`	None	`boolean`	Checks the element's constraint validation and returns true if the element is valid or false if not. If invalid, this method will dispatch a cancelable `invalid` event. If not canceled, a the current `validationMessage` will be reported to the user. https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/reportValidity
`setCustomValidity`	`error`	`void`	Sets the element's constraint validation error message. When set to a non-empty string, `validity.customError` will be true and `validationMessage` will display the provided error. Use this method to customize error messages reported. https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setCustomValidity

Events

Link to “Events”

Event	Type	Bubbles	Composed	Description
`change`	`Event`	Yes	No	The native `change` event on `<input>`
`input`	`InputEvent`	Yes	Yes	The native `input` event on `<input>`