Checkboxes

Checkboxes allow users to select one or more items from a set. Checkboxes can turn an option on or off.

Android check Web Flutter iOS Not available

List of meal options: pickles, tomato, lettuce, and cheese. Each option has a checkbox


Usage

Use checkboxes to:

  • Select one or more options from a list
  • Present a list containing sub-selections
  • Turn an item on or off in a desktop environment

Principles

Familiar

Checkboxes have been in user interfaces for a long time and should be used as expected.

Scannable

It should be visible at a glance if a checkbox has been selected, and selected items should be more visually prominent than unselected items.

Efficient

Checkboxes make it easy to compare available options.


When to use checkboxes

Checkboxes should be used instead of switches if multiple options can be selected from a list.

List of types of emails to receive. Each item has a switch
Don'tIf a list consists of multiple options, don't use switches. Instead, use checkboxes. Checkboxes imply the items are related, and take up less visual space.
List of types of emails to receive. Each option has a checkbox and the first option is a parent control for receiving emails
DoCheckboxes let users select one or more options from a list. A parent checkbox allows for easy selection or deselection of all items.

Other selection controls

Selection controls allow users to complete tasks which involve making choices such as selecting options...

Selection controls allow users to complete tasks which involve making choices such as selecting options, switching settings on or off, or adding or removing items.

Two checkboxes. One is selected and the other is unselected

Checkboxes

Two radio buttons. One is selected and the other is unselected

Radio buttons

Two switches. One is on and the other is off

Switches

Radio buttons and switches are alternative selection controls that can be used to enter decisions or declare preferences such as settings or dialogs.


Platform differences

Adapt selection controls, including checkboxes, to fit platform standards.

Android
Use Material checkboxes.
iOS
Use switches instead of checkboxes and check mark lists instead of radio buttons as these are the graphics expected on iOS.

Behavior

Selecting multiple items in a list using checkboxes
Turning an item on or off using a checkbox

Parent and child checkboxes

Checkboxes can have a parent-child relationship with other checkboxes.

  • When the parent checkbox is checked, all child checkboxes are checked
  • If a parent checkbox is unchecked, all child checkboxes are unchecked
  • If some, but not all, child checkboxes are checked, the parent checkbox becomes an indeterminate checkbox
Checked, unchecked, and indeterminate states of a parent checkbox

States

Checkboxes can be selected, unselected, or indeterminate. Checkboxes have enabled, disabled, hover, focused and pressed states.

Checkboxes can be selected, unselected, or indeterminate. Checkboxes have enabled, disabled, hover, focused and pressed states.

Matrix of all checkbox state combinations
Interaction states for selected, unselected, and indeterminate checkboxes

Theming

Crane Material Theme

This travel app's checkboxes have been customized using Material Theming to use custom color. Crane is a travel app that uses Material Design components...


Specs

Checkboxes

  • Measurement 24
 

Using checkboxes

Before you can use Material checkboxes, you need to add a dependency to the Material Components for Android library. For more information, go to the Getting started page.

Note:<CheckBox> is auto-inflated as <com.google.android.material.button.MaterialCheckBox> via MaterialComponentsViewInflater when using a non-Bridge Theme.MaterialComponents.* theme.

Making checkboxes accessible

Checkboxes support content labeling for accessibility and are readable by most screen readers, such as TalkBack. Text rendered in check boxes is automatically provided to accessibility services. Additional content labels are usually unnecessary.

Checkbox

A checkbox is a square button with a check to denote its current state. Checkboxes allow the user to select one or more items from a set. Checkboxes can be used to turn an option on or off. Unlike radio buttons, changes in the states of one checkbox do not usually affect other checkboxes.

Note: Checkboxes do not support shape theming and are only rounded square checkboxes.

Checkboxes example

API and source code:

The following example shows a list of five checkboxes.

Example of 5 checkboxes, the first one is checked and the last one is
disabled.

In the layout:

In code:

Key properties

Checkbox attributes

ElementAttributeRelated method(s)Default value
To use material colorsapp:useMaterialThemeColorssetUseMaterialThemeColors
isUseMaterialThemeColors
true (ignored if app:buttonTint is set)
Colorapp:buttonTintsetButtonTintList
getButtonTintList
null
Min sizeandroid:minWidth
android:minHeight
(set/get)MinWidth
(set/get)MinHeight
?attr/minTouchTargetSize

The color of the checkbox defaults to ?attr/colorOnSurface (unchecked) and ?attr/colorSecondary (checked) defined in your app theme. If you want to override this behavior, as you might with a custom drawable that should not be tinted, set app:useMaterialThemeColors to false:

Text label attributes

ElementAttributeRelated method(s)Default value
Text labelandroid:textsetText
getText
null
Colorandroid:textColorsetTextColor
getTextColors
inherits from AppCompatCheckBox
Typographyandroid:textAppearancesetTextAppearanceinherits from AppCompatCheckBox

Checkbox states

Checkboxes can be selected, unselected, or indeterminate. Checkboxes have enabled, disabled, hover, focused, and pressed states.

Checkbox states in an array. Columns are enabled, disabled, hover, focused,
pressed. Rows are selected, unselected, or
indeterminite

Note:MaterialCheckBox does not support the indeterminate state. Only selected and unselected states are supported.

Styles

ElementStyle
Default styleWidget.MaterialComponents.CompoundButton.CheckBox

Default style theme attribute: ?attr/checkboxStyle

See the full list of styles and attrs.

Theming checkboxes

Checkboxes support Material Theming and can be customized in terms of color and typography.

Checkbox theming example

API and source code:

The following example shows a checkbox with Material Theming.

"5 checkboxes with brown text and box outlines, checkbox 1 is selected box
with pink fill and white checkmark"

Implementing checkbox theming

Using theme attributes in res/values/styles.xml (themes all checkboxes and affects other components):

or using default style theme attributes, styles and theme overlays (themes all checkboxes but does not affect other components):

you can also change the checkbox colors via the ?attr/buttonTint attribute:

and in color/button_tint.xml:

or using the styles in the layout (affects only this checkbox):

No Android implementation guidance available

Using checkboxes

Checkboxes allow the user to select one or more items from a set. Checkboxes can be used to turn an option on or off.

Installing checkboxes

Styles

Note: The form field styles are only required when the checkbox is used with the form field.

JavaScript instantiation

The checkbox will work without JavaScript, but you can enhance it with a ripple interaction effect by instantiating MDCCheckbox on the mdc-checkbox element. To activate the ripple effect upon interacting with the label, you must also instantiate MDCFormField on the mdc-form-field element and set the MDCCheckbox instance as its input.

See Importing the JS component for more information on how to import JavaScript.

Making checkboxes accessible

Material Design spec advises that touch targets should be at least 48px x 48px. To meet this requirement, add the mdc-checkbox--touch class to your checkbox as follows:

Note that the outer mdc-touch-target-wrapper element is only necessary if you want to avoid potentially overlapping touch targets on adjacent elements (due to collapsing margins).

Checkboxes

We recommend using MDC Checkbox with MDC Form Field for enhancements such as label alignment, label activation of the ripple interaction effect, and RTL-awareness.

Checkbox example

Note: If you are using IE, you need to include a closing </path> tag if you wish to avoid console warnings.

Checkbox states

Checkboxes can be selected, unselected, or indeterminate. Checkboxes have enabled, disabled, hover, focused, and pressed states.

Checkbox states in a table. Columns are enabled, disabled, hover, focused, pressed. Rows are selected, unselected, or indeterminite

Other variants

Disabled checkboxes

Note that mdc-checkbox--disabled is necessary on the root element of CSS-only checkboxes to prevent hover states from activating. Checkboxes that use the JavaScript component do not need this class; a disabled attribute on the <input> element is sufficient.

Indeterminate checkboxes

Note that data-indeterminate="true" is necessary on the input element for initial render, or in a CSS-only mode. Checkboxes that use the Javascript component can modify the indeterminate property at runtime.

API

Sass mixins

MDC Checkbox uses MDC Theme's secondary color by default for "marked" states (i.e., checked or indeterminate).

MixinDescription
container-colors($unmarked-stroke-color, $unmarked-fill-color, $marked-stroke-color, $marked-fill-color, $generate-keyframes)Sets stroke & fill colors for both marked and unmarked state of enabled checkbox. Set $generate-keyframes to false to prevent the mixin from generating @keyframes.
disabled-container-colors($unmarked-stroke-color, $unmarked-fill-color, $marked-stroke-color, $marked-fill-color)Sets stroke & fill colors for both marked and unmarked state of disabled checkbox.
ink-color($color)Sets the ink color of the checked and indeterminate icons for an enabled checkbox
disabled-ink-color($color)Sets the ink color of the checked and indeterminate icons for a disabled checkbox
focus-indicator-color($color)Sets the color of the focus indicator (ripple) when checkbox is selected or is in indeterminate state.
ripple-size($ripple-size)Sets the ripple size of the checkbox.
density($density-scale)Sets density scale for checkbox, Supported density scales are -3, -2, -1, and 0 (default).

The ripple effect for the Checkbox component is styled using MDC Ripple mixins.

MDCCheckbox properties and methods

Property NameTypeDescription
checkedbooleanSetter/getter for the checkbox's checked state
indeterminatebooleanSetter/getter for the checkbox's indeterminate state
disabledbooleanSetter/getter for the checkbox's disabled state
valuestringSetter/getter for the checkbox's

Usage within web frameworks

If you are using a JavaScript framework, such as React or Angular, you can create a Checkbox for your framework. Depending on your needs, you can use the Simple Approach: Wrapping MDC Web Vanilla Components, or the Advanced Approach: Using Foundations and Adapters. Please follow the instructions here.

MDCCheckboxAdapter

Method SignatureDescription
addClass(className: string) => voidAdds a class to the root element.
removeClass(className: string) => voidRemoves a class from the root element.
forceLayout() => voidForce-trigger a layout on the root element. This is needed to restart animations correctly. If you find that you do not need to do this, you can simply make it a no-op.
isAttachedToDOM() => booleanReturns true if the component is currently attached to the DOM, false otherwise.
isIndeterminate() => booleanReturns true if the component is in the indeterminate state.
isChecked() => booleanReturns true if the component is checked.
hasNativeControl() => booleanReturns true if the input is present in the component.
setNativeControlDisabled(disabled: boolean) => voidSets the input to disabled.
setNativeControlAttr(attr: string, value: string) => voidSets an HTML attribute to the given value on the native input element.
removeNativeControlAttr(attr: string) => voidRemoves an attribute from the native input element.

MDCCheckboxFoundation

Method SignatureDescription
setDisabled(disabled: boolean) => voidUpdates the disabled property on the underlying input. Does nothing when the underlying input is not present.
handleAnimationEnd() => voidanimationend event handler that should be applied to the root element.
handleChange() => voidchange event handler that should be applied to the checkbox element.
No Web implementation guidance available

Using checkboxes

Checkboxes allow the user to select one or more items from a set. Checkboxes can be used to turn an option on or off.

Making checkboxes accessible

Flutter's APIs support accessibility setting for large fonts, screen readers, and sufficient contrast. For more information, go to Flutter's accessibility and internationalization pages.

Checkboxes

Checkboxes example

CheckBox

The following example should five checkboxes. The first one is enabled, the second one has tristate enabled, and the last one is disabled.

Checkboxes example.

Checkbox states

Checkboxes can be selected, unselected, or indeterminate. Checkboxes have enabled, disabled, hover, focused, and pressed states.

Checkbox states in an array. Columns are enabled, disabled, hover, focused, pressed. Rows are selected, unselected, or indeterminite

Checkbox key properties

Checkbox attributes

 Property
ColoractiveColor on Checkbox
Checkedvalue on Checkbox
Tristatetristate on Checkbox
Disabledpass null to onChanged on Checkbox

Theming

Checkboxes support Material Theming and can be customized in terms of color, typography and shape.

The following example shows checkboxes with the Material Shrine Theme.

Checkboxes example with Shrine theme.

No Flutter implementation guidance available
No iOS implementation guidance available

Up next