CheckBox

Checkboxes let people confirm independent selections while preserving clear unchecked, checked, and disabled states. Use presentation when the checkbox is only a visual indicator inside another accessible control, such as a clickable ListItem.

Receive notifications

Checked: false

In presentation mode, the control occupies only --md-checkbox-container-size (18dp by default), without an independent hit target. --md-checkbox-target-size applies only to standalone interactive checkboxes (40dp by default). The parent owns spacing and interaction; this works with both ListItem and MenuItem. An explicitly larger container can grow the parent row.

Density

Default geometry follows the body-medium font size. The dimensions below describe default typography; compact and custom typography scale the baseline and its bounds before applying density. Explicit geometry tokens bypass this calculation.

The visible shape starts at 18dp and changes by 1dp per --md-density step, clamped to 14–22dp. Selection marks and default stroke widths scale proportionally. This also applies in presentation mode, where the parent owns spacing and interaction.

Standalone targets start at 40dp and change by 2dp per density step, retaining at least 4dp on each side of the visible shape. The state layer follows the target, shrinking more slowly than menu row spacing to keep hover feedback visible. Explicit shape and target-size tokens override their respective defaults. Icon source calibration and --md-icon-scale do not affect these controls.

density 0density -2density -4

Examples

Default

Receive notifications

Checked: false

States

UncheckedCheckedDisabled uncheckedDisabled checked

Mixed state

checked owns the submitted boolean value; indeterminate owns the mixed visual state and native input.indeterminate property. Use v-model:indeterminate for local state or pass a computed prop for consumer-owned group state. Mixed presentation takes precedence over the checkmark and exposes aria-checked="mixed" on the native input.

User activation follows native checkbox behavior: toggles checked, emits update:checked, then clears indeterminate with update:indeterminate(false). Disabled checkboxes do not update. Presentation mode renders no input and emits no interactions; the parent owns all semantics. The component never derives group selection.

Export channelsColorDepthMask

Reference

Anatomy

Highlight

Element	Part	Selector
<component>	root	[data-scope="checkbox"][data-part="root"] left_clickLMBCopy
<input>	inputconditional	[data-scope="checkbox"][data-part="input"] left_clickLMBCopy
<span>	control	[data-scope="checkbox"][data-part="control"] left_clickLMBCopy
<span>	box	[data-scope="checkbox"][data-part="box"] left_clickLMBCopy
<span>	icon	[data-scope="checkbox"][data-part="icon"] left_clickLMBCopy
<span>	labelconditional	[data-scope="checkbox"][data-part="label"] left_clickLMBCopy

Props

Name	Description	Default	Control
shapeOptional	Corner style; inherits the shared shape default. M3Shape | undefined	-	-
disabledOptional	Whether the checkbox is disabled. boolean | undefined	false
presentationOptional	Render only the visual checkbox. The parent must provide interaction semantics. boolean | undefined	false
nameOptional	Name attribute for the native checkbox input. string | undefined	-	-
valueOptional	Value attribute for the native checkbox input. string | undefined	-	-
ariaLabelOptional	ARIA label forwarded to the native checkbox input. string | undefined	-	-
indeterminateOptional	- boolean | undefined	false
checkedRequired	- boolean	-

Events2

Name	Type	Description
update:indeterminate	[value: boolean]	-
update:checked	[value: boolean]	-

Slots1

Name	Parameters	Description
default	-	Optional label content rendered next to checkbox.

Styling25

Preview

Token	Description
--md-checkbox-colorColor Fallbackvar(--md-sys-color-primary)	Default selected container color and selected state layer color.
--md-checkbox-on-colorColor Fallbackvar(--md-sys-color-on-primary)	Default selected icon color.
--md-checkbox-unselected-outline-colorColor Fallbackvar(--md-sys-color-on-surface-variant)	Outline color for the unchecked box.
--md-checkbox-selected-container-colorColor Fallbackvar(--md-checkbox-color)	Container color for the checked box.
--md-checkbox-selected-icon-colorColor Fallbackvar(--md-checkbox-on-color)	Checkmark color for the checked box.
--md-checkbox-unselected-state-layer-colorState Fallbackvar(--md-sys-color-on-surface)	State layer color when unchecked.
--md-checkbox-state-layer-colorState Fallbackvar(--md-checkbox-color)	Shortcut for the checked state layer color.
--md-checkbox-selected-state-layer-colorState Fallbackvar(--md-checkbox-state-layer-color)	State layer color when checked.
--md-checkbox-disabled-colorDisabled Fallbackvar(--md-sys-color-on-surface)	Base color used by disabled checkbox visuals.
--md-checkbox-disabled-opacityDisabled Fallback0.38	Default opacity for disabled checkbox visuals.
--md-checkbox-disabled-unselected-outline-colorDisabled Fallbackvar(--md-checkbox-disabled-color)	Outline color for disabled unchecked state.
--md-checkbox-disabled-unselected-outline-opacityDisabled Fallbackvar(--md-checkbox-disabled-opacity)	Outline opacity for disabled unchecked state.
--md-checkbox-disabled-selected-container-colorDisabled Fallbackvar(--md-checkbox-disabled-color)	Container color for disabled checked state.
--md-checkbox-disabled-selected-container-opacityDisabled Fallbackvar(--md-checkbox-disabled-opacity)	Container opacity for disabled checked state.
--md-checkbox-disabled-selected-icon-colorDisabled Fallbackvar(--md-sys-color-surface)	Checkmark color for disabled checked state.
--md-checkbox-disabled-selected-icon-opacityDisabled Fallbackvar(--md-checkbox-disabled-opacity)	Checkmark opacity for disabled checked state.
--md-checkbox-label-colorLabel Fallbackvar(--md-sys-color-on-surface)	Color of the optional label slot.
--md-checkbox-container-sizeLayout FallbackTypography and density (18dp at default typography and density 0)	Size of the visible checkbox box.
--md-checkbox-target-sizeLayout Fallback40dp + 2dp per density step; at least box size + 8dp; presentation uses box size	Size of the interactive control and state layer area.
--md-checkbox-state-layer-shapeShape Fallbackvar(--md-sys-shape-corner-full)	Shape of the state layer area.
--md-checkbox-shapeShape Fallback--dp(2)	Corner radius of the visible checkbox box.
--md-checkbox-outline-widthLayout FallbackResolved box size / 9	Outline width of the unchecked box.
--md-checkbox-focus-indicator-colorFocus Fallbackvar(--md-sys-color-secondary)	Focus ring color.
--md-checkbox-focus-indicator-thicknessFocus Fallbackvar(--md-sys-state-focus-indicator-thickness)	Focus ring thickness.
--md-checkbox-focus-indicator-offsetFocus Fallbackvar(--md-sys-state-focus-indicator-outer-offset)	Focus ring offset.