Skip to main content

​
Overview

<mat-checkbox> provides the same functionality as a native <input type="checkbox"> enhanced with Material Design styling and animations.

​
Basic Usage

<mat-checkbox>Check me!</mat-checkbox>

​
API Reference

​
MatCheckbox

Selector: mat-checkbox Exported as: matCheckbox

​
Inputs

​
checked
boolean
default:"false"
Whether the checkbox is checked.
​
disabled
boolean
default:"false"
Whether the checkbox is disabled.
​
indeterminate
boolean
default:"false"
Whether the checkbox is indeterminate. This is also known as “mixed” mode and can be used to represent a checkbox with three states.
​
labelPosition
'before' | 'after'
default:"'after'"
Whether the label should appear after or before the checkbox. Defaults to ‘after’.
​
required
boolean
default:"false"
Whether the checkbox is required.
​
color
ThemePalette
Theme color of the checkbox. This API is supported in M2 themes only.
​
disableRipple
boolean
default:"false"
Whether the checkbox has a ripple.
​
disabledInteractive
boolean
default:"false"
Whether the checkbox should remain interactive when it is disabled.
​
value
string
The value attribute of the native input element.
​
id
string
A unique id for the checkbox input. If none is supplied, it will be auto-generated.
​
name
string | null
default:"null"
Name value will be applied to the input element if present.
​
tabIndex
number
default:"0"
Tabindex for the checkbox.
​
aria-label
string
default:"''"
Attached to the aria-label attribute of the host element.
​
aria-labelledby
string | null
default:"null"
Users can specify the aria-labelledby attribute which will be forwarded to the input element.
​
aria-describedby
string
The ‘aria-describedby’ attribute is read after the element’s label and field type.

​
Outputs

​
change
EventEmitter<MatCheckboxChange>
Event emitted when the checkbox’s checked value changes.
​
indeterminateChange
EventEmitter<boolean>
Event emitted when the checkbox’s indeterminate value changes.

​
Methods

​
focus()
void
Focuses the checkbox.
​
toggle()
void
Toggles the checked state of the checkbox.

​
MatCheckboxChange

​
source
MatCheckbox
The source checkbox of the event.
​
checked
boolean
The new checked value of the checkbox.

​
Accessibility

  • The checkbox uses a native <input type="checkbox"> element
  • The checkbox label is associated with the input using a <label> element
  • Use aria-label or aria-labelledby when the checkbox doesn’t have a visible label
  • The component supports keyboard interaction (Space to toggle)
  • Disabled checkboxes are not focusable and are announced as disabled to screen readers

​
Advanced Usage

​
Indeterminate State

The indeterminate state is useful when dealing with nested checkboxes: 
export class CheckboxIndeterminateExample {
  allComplete: boolean = false;
  
  task = {
    name: 'Indeterminate',
    completed: false,
    subtasks: [
      {name: 'Primary', completed: false},
      {name: 'Accent', completed: false},
    ]
  };
  
  updateAllComplete() {
    this.allComplete = this.task.subtasks != null && 
      this.task.subtasks.every(t => t.completed);
  }
  
  someComplete(): boolean {
    return this.task.subtasks.filter(t => t.completed).length > 0 && !this.allComplete;
  }
  
  setAll(completed: boolean) {
    this.allComplete = completed;
    this.task.subtasks.forEach(t => t.completed = completed);
  }
}

<mat-checkbox
  [checked]="allComplete"
  [indeterminate]="someComplete()"
  (change)="setAll($event.checked)">
  Complete all
</mat-checkbox>

​
Label Position

<mat-checkbox labelPosition="before">Before label</mat-checkbox>

​
Disabled Interactive

Allow disabled checkboxes to remain interactive: 
<mat-checkbox [disabled]="true" [disabledInteractive]="true">
  Disabled but interactive
</mat-checkbox>

Build docs developers (and LLMs) love

Get started for freeTalk to us