Checkbox

API for checkbox

API reference for Angular Material checkbox

import {MatCheckboxModule} from '@angular/material/checkbox';

A material design checkbox component. Supports all of the functionality of an HTML5 checkbox, and exposes a similar API. A MatCheckbox can be either checked, unchecked, indeterminate, or disabled. Note that all additional accessibility attributes are taken care of by the component, so there is no need to provide them yourself. However, if you want to omit a label and still have the checkbox be accessible, you may supply an [aria-label] input. See: https://material.io/design/components/selection-controls.html

Selector: mat-checkbox

Exported as: matCheckbox
Properties
Name Description
@Input('aria-describedby')

ariaDescribedby: string

The 'aria-describedby' attribute is read after the element's label and field type.

@Input('aria-label')

ariaLabel: string

Attached to the aria-label attribute of the host element. In most cases, aria-labelledby will take precedence so this may be omitted.

@Input('aria-labelledby')

ariaLabelledby: string | null

Users can specify the aria-labelledby attribute which will be forwarded to the input element

@Input()

checked: boolean

Whether the checkbox is checked.

@Input()

color: ThemePalette

Theme color palette for the component.

@Input()

disableRipple: boolean

Whether ripples are disabled.

@Input()

disabled: any

Whether the checkbox is disabled. This fully overrides the implementation provided by mixinDisabled, but the mixin is still required because mixinTabIndex requires it.

@Input()

id: string

A unique id for the checkbox input. If none is supplied, it will be auto-generated.

@Input()

indeterminate: boolean

Whether the checkbox is indeterminate. This is also known as "mixed" mode and can be used to represent a checkbox with three states, e.g. a checkbox that represents a nested list of checkable items. Note that whenever checkbox is manually clicked, indeterminate is immediately set to false.

@Input()

labelPosition: 'before' | 'after'

Whether the label should appear after or before the checkbox. Defaults to 'after'

@Input()

name: string | null

Name value will be applied to the input element if present

@Input()

required: boolean

Whether the checkbox is required.

@Input()

value: string

The value attribute of the native input element

@Output()

change: EventEmitter<MatCheckboxChange>

Event emitted when the checkbox's checked value changes.

@Output()

indeterminateChange: EventEmitter<boolean>

Event emitted when the checkbox's indeterminate value changes.

defaultColor: ThemePalette | undefined

Default color to fall back to if no value is set.

defaultTabIndex: number

Tabindex to which to fall back to if no value is set.

inputId: string

Returns the unique id for the visual hidden input.

ripple: MatRipple

Reference to the ripple instance of the checkbox.

Methods
focus

Focuses the checkbox.

Parameters

origin

FocusOrigin = 'keyboard'

options?

FocusOptions

toggle

Toggles the checked state of the checkbox.

Validator for Material checkbox's required attribute in template-driven checkbox. Current CheckboxRequiredValidator only work with input type=checkbox and does not work with mat-checkbox.

Selector: mat-checkbox[required][formControlName] mat-checkbox[required][formControl] mat-checkbox[required][ngModel]

Properties
Name Description

required: boolean | string

Methods
registerOnValidatorChange
Parameters

fn

() => void

validate
Parameters

control

AbstractControl

Returns
ValidationErrors | null

Change event object emitted by MatCheckbox.

Properties
Name Description

checked: boolean

The new checked value of the checkbox.

source: MatCheckbox

The source MatCheckbox of the event.

Default mat-checkbox options that can be overridden.

Properties
Name Description

clickAction: MatCheckboxClickAction

color: ThemePalette

Checkbox click action when user click on input element. noop: Do not toggle checked or indeterminate. check: Only toggle checked status, ignore indeterminate. check-indeterminate: Toggle checked status, set indeterminate to false. Default behavior. undefined: Same as check-indeterminate.

type MatCheckboxClickAction = 'noop' | 'check' | 'check-indeterminate' | undefined;

Injection token to be used to override the default options for mat-checkbox.

const MAT_CHECKBOX_DEFAULT_OPTIONS: InjectionToken<MatCheckboxDefaultOptions>;
Deprecated

Injection token that can be used to specify the checkbox click behavior.

const MAT_CHECKBOX_CLICK_ACTION: InjectionToken<MatCheckboxClickAction>;
const MAT_CHECKBOX_REQUIRED_VALIDATOR: Provider;

API reference for Angular Material checkbox-testing

import {MatCheckboxHarness} from '@angular/material/checkbox/testing';

Harness for interacting with a standard mat-checkbox in tests.

Methods
async
blur

Blurs the checkbox.

Returns
Promise<void>

Promise that resolves when the action completes.

async
check

Puts the checkbox in a checked state by toggling it if it is currently unchecked, or doing nothing if it is already checked.

Note: This attempts to check the checkbox as a user would, by clicking it. Therefore if you are using MAT_CHECKBOX_CLICK_ACTION to change the behavior on click, calling this method might not have the expected result.

Returns
Promise<void>

Promise that resolves when the action completes.

async
focus

Focuses the checkbox.

Returns
Promise<void>

Promise that resolves when the action completes.

async
getAriaLabel

Gets the checkbox's aria-label.

Returns
Promise<string | null>

async
getAriaLabelledby

Gets the checkbox's aria-labelledby.

Returns
Promise<string | null>

async
getLabelText

Gets the checkbox's label text.

Returns
Promise<string>

async
getName

Gets the checkbox's name.

Returns
Promise<string | null>

async
getValue

Gets the checkbox's value.

Returns
Promise<string | null>

async
host

Gets a Promise for the TestElement representing the host element of the component.

Returns
Promise<TestElement>

async
isChecked

Whether the checkbox is checked.

Returns
Promise<boolean>

async
isDisabled

Whether the checkbox is disabled.

Returns
Promise<boolean>

async
isFocused

Whether the checkbox is focused.

Returns
Promise<boolean>

async
isIndeterminate

Whether the checkbox is in an indeterminate state.

Returns
Promise<boolean>

async
isRequired

Whether the checkbox is required.

Returns
Promise<boolean>

async
isValid

Whether the checkbox is valid.

Returns
Promise<boolean>

async
toggle

Toggles the checked state of the checkbox.

Note: This attempts to toggle the checkbox as a user would, by clicking it. Therefore if you are using MAT_CHECKBOX_CLICK_ACTION to change the behavior on click, calling this method might not have the expected result.

Returns
Promise<void>

Promise that resolves when the action completes.

async
uncheck

Puts the checkbox in an unchecked state by toggling it if it is currently checked, or doing nothing if it is already unchecked.

Note: This attempts to uncheck the checkbox as a user would, by clicking it. Therefore if you are using MAT_CHECKBOX_CLICK_ACTION to change the behavior on click, calling this method might not have the expected result.

Returns
Promise<void>

Promise that resolves when the action completes.

A set of criteria that can be used to filter a list of MatCheckboxHarness instances.

Properties
Name Description

label: string | RegExp

Only find instances whose label matches the given value.

name: string

Only find instances whose name attribute is the given value.