Overview for checkbox
<mat-checkbox>
provides the same functionality as a native <input type="checkbox">
enhanced with Material Design styling and animations.
Checkbox label
The checkbox label is provided as the content to the <mat-checkbox>
element. The label can be
positioned before or after the checkbox by setting the labelPosition
property to 'before'
or
'after'
.
If you don't want the label to appear next to the checkbox, you can use
aria-label
or
aria-labelledby
to
specify an appropriate label.
Use with @angular/forms
<mat-checkbox>
is compatible with @angular/forms
and supports both FormsModule
and ReactiveFormsModule
.
Indeterminate state
<mat-checkbox>
supports an indeterminate
state, similar to the native <input type="checkbox">
.
While the indeterminate
property of the checkbox is true, it will render as indeterminate
regardless of the checked
value. Any interaction with the checkbox by a user (i.e., clicking) will
remove the indeterminate state.
Click action config
When user clicks on the mat-checkbox
, the default behavior is toggle checked
value and set
indeterminate
to false
. This behavior can be customized by
providing a new value
of MAT_CHECKBOX_DEFAULT_OPTIONS
to the checkbox.
providers: [
{provide: MAT_CHECKBOX_DEFAULT_OPTIONS, useValue: { clickAction: 'noop' } as MatCheckboxDefaultOptions}
]
The possible values are:
noop
Do not change the checked
value or indeterminate
value. Developers have the power to
implement customized click actions.
check
Toggle checked
value of the checkbox, ignore indeterminate
value. If the
checkbox is in indeterminate
state, the checkbox will display as an indeterminate
checkbox
regardless the checked
value.
check-indeterminate
Default behavior of mat-checkbox
. Always set indeterminate
to false
when user click on the mat-checkbox
.
This matches the behavior of native <input type="checkbox">
.
Accessibility
MatCheckbox
uses an internal <input type="checkbox">
to provide an accessible experience.
This internal checkbox receives focus and is automatically labelled by the text content of the
<mat-checkbox>
element. Avoid adding other interactive controls into the content of
<mat-checkbox>
, as this degrades the experience for users of assistive technology.
Always provide an accessible label via aria-label
or aria-labelledby
for checkboxes without
descriptive text content. For dynamic labels, MatCheckbox
provides input properties for binding
aria-label
and aria-labelledby
. This means that you should not use the attr.
prefix when
binding these properties, as demonstrated below.
<mat-checkbox [aria-label]="isSubscribedToEmailsMessage">
</mat-checkbox>
Additionally, MatCheckbox
now supports the following accessibility properties:
aria-expanded
: Indicates whether the checkbox controls the visibility of another element. This should be a boolean value (true
orfalse
).aria-controls
: Specifies the ID of the element that the checkbox controls.aria-owns
: Specifies the ID of the element that the checkbox visually owns.