API for checkbox

API reference for Angular Material checkbox

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

Selector: mat-checkbox

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

ariaControls: string

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

@Input('aria-describedby')

ariaDescribedby: string

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

@Input({ alias: 'aria-expanded', transform: booleanAttribute })

ariaExpanded: boolean

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

@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('aria-owns')

ariaOwns: string

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

@Input({ transform: booleanAttribute })

checked: boolean

Whether the checkbox is checked.

@Input()

color: string | undefined

Theme color of the checkbox. This API is supported in M2 themes only, it has no effect in M3 themes. For color customization in M3, see https://material.angular.io/components/checkbox/styling.

For information on applying color variants in M3, see https://material.angular.io/guide/material-2-theming#optional-add-backwards-compatibility-styles-for-color-variants

@Input({ transform: booleanAttribute })

disableRipple: boolean

Whether the checkbox has a ripple.

@Input({ transform: booleanAttribute })

disabled: boolean

Whether the checkbox is disabled.

@Input({ transform: booleanAttribute })

disabledInteractive: boolean

Whether the checkbox should remain interactive when it is disabled.

@Input()

id: string

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

@Input({ transform: booleanAttribute })

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({ transform: booleanAttribute })

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.

inputId: string

Returns the unique id for the visual hidden input.

Methods
focus

Focuses the checkbox.

registerOnValidatorChange
Parameters

fn

() => void

toggle

Toggles the checked state of the checkbox.

validate
Parameters

control

AbstractControl<boolean, boolean>

Returns
ValidationErrors | null

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]

Deprecated
Properties
Name Description

required: boolean | string

Tracks changes to the required attribute bound to this directive.

Methods
enabled
Parameters

input

boolean

Returns
boolean

registerOnValidatorChange
Parameters

fn

() => void

validate
Parameters

control

AbstractControl<any, any>

Returns
ValidationErrors | null

Change event object emitted by checkbox.

Properties
Name Description

checked: boolean

The new checked value of the checkbox.

source: MatCheckbox

The source checkbox of the event.

Default mat-checkbox options that can be overridden.

Properties
Name Description

clickAction: MatCheckboxClickAction

Default checkbox click action for checkboxes.

color: ThemePalette

Default theme color of the checkbox. This API is supported in M2 themes only, it has no effect in M3 themes. For color customization in M3, see https://material.angular.io/components/checkbox/styling.

For information on applying color variants in M3, see https://material.angular.io/guide/material-2-theming#optional-add-backwards-compatibility-styles-for-color-variants

disabledInteractive: boolean

Whether disabled checkboxes should be interactive.

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;
Deprecated
const MAT_CHECKBOX_CONTROL_VALUE_ACCESSOR: any;

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

const MAT_CHECKBOX_DEFAULT_OPTIONS: InjectionToken<MatCheckboxDefaultOptions>;
Deprecated
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 mat-checkbox in tests.

Properties
Name Description

static hostSelector: '.mat-mdc-checkbox'

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

static
with

Gets a HarnessPredicate that can be used to search for a checkbox with specific attributes.

Parameters

options

CheckboxHarnessFilters = {}

Options for narrowing the search:

  • selector finds a checkbox whose host element matches the given selector.
  • label finds a checkbox with specific label text.
  • name finds a checkbox with specific name.

Returns
HarnessPredicate<T>

a HarnessPredicate configured with the given options.

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

Properties
Name Description

checked: boolean

Only find instances with the given checked value.

disabled: boolean

Only find instances which match the given disabled state.

label: string | RegExp

Only find instances whose label matches the given value.

name: string

Only find instances whose name attribute is the given value.

Azure & Blue theme selected.