docs(material/checkbox): Update checkbox docs & examples

Author: mmalerba

src/components-examples/material/checkbox/checkbox-configurable/checkbox-configurable-example.ts

@@ -1,8 +1,8 @@
-import {Component} from '@angular/core';
-import {MatRadioModule} from '@angular/material/radio';
+import {ChangeDetectionStrategy, Component} from '@angular/core';
 import {FormsModule} from '@angular/forms';
-import {MatCheckboxModule} from '@angular/material/checkbox';
 import {MatCardModule} from '@angular/material/card';
+import {MatCheckboxModule} from '@angular/material/checkbox';
+import {MatRadioModule} from '@angular/material/radio';
 
 /**
  * @title Configurable checkbox
@@ -13,6 +13,7 @@ import {MatCardModule} from '@angular/material/card';
   styleUrl: 'checkbox-configurable-example.css',
   standalone: true,
   imports: [MatCardModule, MatCheckboxModule, FormsModule, MatRadioModule],
+  changeDetection: ChangeDetectionStrategy.OnPush,
 })
 export class CheckboxConfigurableExample {
   checked = false;

src/components-examples/material/checkbox/checkbox-harness/checkbox-harness-example.ts

@@ -1,4 +1,4 @@
-import {Component} from '@angular/core';
+import {ChangeDetectionStrategy, Component} from '@angular/core';
 import {MatCheckboxModule} from '@angular/material/checkbox';
 
 /**
@@ -9,6 +9,7 @@ import {MatCheckboxModule} from '@angular/material/checkbox';
   templateUrl: 'checkbox-harness-example.html',
   standalone: true,
   imports: [MatCheckboxModule],
+  changeDetection: ChangeDetectionStrategy.OnPush,
 })
 export class CheckboxHarnessExample {
   disabled = true;

src/components-examples/material/checkbox/checkbox-overview/checkbox-overview-example.html

@@ -5,21 +5,20 @@
 
 <section class="example-section">
   <span class="example-list-section">
-    <mat-checkbox class="example-margin"
-                  [checked]="allComplete"
-                  [color]="task.color"
-                  [indeterminate]="someComplete()"
-                  (change)="setAll($event.checked)">
+    <mat-checkbox
+      class="example-margin"
+      [checked]="allComplete"
+      [indeterminate]="someComplete()"
+      (change)="setAll($event.checked)"
+    >
       {{task.name}}
     </mat-checkbox>
   </span>
   <span class="example-list-section">
     <ul>
       @for (subtask of task.subtasks; track subtask) {
         <li>
-          <mat-checkbox [(ngModel)]="subtask.completed"
-                        [color]="subtask.color"
-                        (ngModelChange)="updateAllComplete()">
+          <mat-checkbox [(ngModel)]="subtask.completed" (ngModelChange)="updateAllComplete()">
             {{subtask.name}}
           </mat-checkbox>
         </li>

src/components-examples/material/checkbox/checkbox-overview/checkbox-overview-example.ts

@@ -1,12 +1,10 @@
-import {Component} from '@angular/core';
-import {ThemePalette} from '@angular/material/core';
+import {ChangeDetectionStrategy, Component} from '@angular/core';
 import {FormsModule} from '@angular/forms';
 import {MatCheckboxModule} from '@angular/material/checkbox';
 
 export interface Task {
   name: string;
   completed: boolean;
-  color: ThemePalette;
   subtasks?: Task[];
 }
 
@@ -19,16 +17,16 @@ export interface Task {
   styleUrl: 'checkbox-overview-example.css',
   standalone: true,
   imports: [MatCheckboxModule, FormsModule],
+  changeDetection: ChangeDetectionStrategy.OnPush,
 })
 export class CheckboxOverviewExample {
-  task: Task = {
-    name: 'Indeterminate',
+  readonly task: Task = {
+    name: 'Parent task',
     completed: false,
-    color: 'primary',
     subtasks: [
-      {name: 'Primary', completed: false, color: 'primary'},
-      {name: 'Accent', completed: false, color: 'accent'},
-      {name: 'Warn', completed: false, color: 'warn'},
+      {name: 'Child task 1', completed: false},
+      {name: 'Child task 2', completed: false},
+      {name: 'Child task 3', completed: false},
     ],
   };
 

src/components-examples/material/checkbox/checkbox-reactive-forms/checkbox-reactive-forms-example.ts

@@ -1,6 +1,6 @@
-import {Component} from '@angular/core';
-import {FormBuilder, FormsModule, ReactiveFormsModule} from '@angular/forms';
 import {JsonPipe} from '@angular/common';
+import {ChangeDetectionStrategy, Component, inject} from '@angular/core';
+import {FormBuilder, FormsModule, ReactiveFormsModule} from '@angular/forms';
 import {MatCheckboxModule} from '@angular/material/checkbox';
 
 /** @title Checkboxes with reactive forms */
@@ -10,13 +10,14 @@ import {MatCheckboxModule} from '@angular/material/checkbox';
   styleUrl: 'checkbox-reactive-forms-example.css',
   standalone: true,
   imports: [FormsModule, ReactiveFormsModule, MatCheckboxModule, JsonPipe],
+  changeDetection: ChangeDetectionStrategy.OnPush,
 })
 export class CheckboxReactiveFormsExample {
-  toppings = this._formBuilder.group({
+  private readonly _formBuilder = inject(FormBuilder);
+
+  readonly toppings = this._formBuilder.group({
     pepperoni: false,
     extracheese: false,
     mushroom: false,
   });
-
-  constructor(private _formBuilder: FormBuilder) {}
 }

src/material/checkbox/checkbox-config.ts

@@ -10,7 +10,11 @@ import {ThemePalette} from '@angular/material/core';
 
 /** Default `mat-checkbox` options that can be overridden. */
 export interface MatCheckboxDefaultOptions {
-  /** Default theme color palette to be used for checkboxes. */
+  /**
+   * Default theme color palette to be used for checkboxes. This API is supported in M2 themes
+   * only, it has no effect in M3 themes. For information on applying color variants in M3, see
+   * https://material.angular.io/guide/theming#using-component-color-variants
+   */
   color?: ThemePalette;
   /** Default checkbox click action for checkboxes. */
   clickAction?: MatCheckboxClickAction;

src/material/checkbox/checkbox.md

@@ -4,6 +4,7 @@ enhanced with Material Design styling and animations.
 <!-- example(checkbox-overview) -->
 
 ### 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'`.
@@ -14,16 +15,19 @@ If you don't want the label to appear next to the checkbox, you can use
 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](https://angular.io/guide/dependency-injection)
@@ -38,22 +42,27 @@ providers: [
 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">`.
 
 ### Theming
-The color of a `<mat-checkbox>` can be changed by using the `color` property. By default, checkboxes
-use the theme's accent color. This can be changed to `'primary'` or `'warn'`.
+
+The color of a `<mat-checkbox>` can be changed by specifying a `$color-variant` when applying the
+`mat.checkbox-theme` or `mat.checkbox-color` mixins. By default, checkboxes use the theme's primary
+palette. This can be changed to `'secondary'`, `'tertiary'`, or `'error'`.
 
 ### Accessibility
 

src/material/checkbox/checkbox.ts

@@ -6,27 +6,28 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
+import {FocusableOption} from '@angular/cdk/a11y';
 import {
+  ANIMATION_MODULE_TYPE,
   AfterViewInit,
   Attribute,
-  booleanAttribute,
   ChangeDetectionStrategy,
   ChangeDetectorRef,
   Component,
   ElementRef,
   EventEmitter,
-  forwardRef,
   Inject,
   Input,
   NgZone,
-  numberAttribute,
   OnChanges,
   Optional,
   Output,
   SimpleChanges,
   ViewChild,
   ViewEncapsulation,
-  ANIMATION_MODULE_TYPE,
+  booleanAttribute,
+  forwardRef,
+  numberAttribute,
 } from '@angular/core';
 import {
   AbstractControl,
@@ -36,8 +37,7 @@ import {
   ValidationErrors,
   Validator,
 } from '@angular/forms';
-import {_MatInternalFormField, MatRipple} from '@angular/material/core';
-import {FocusableOption} from '@angular/cdk/a11y';
+import {MatRipple, _MatInternalFormField} from '@angular/material/core';
 import {
   MAT_CHECKBOX_DEFAULT_OPTIONS,
   MAT_CHECKBOX_DEFAULT_OPTIONS_FACTORY,
@@ -202,7 +202,11 @@ export class MatCheckbox
 
   // TODO(crisbeto): this should be a ThemePalette, but some internal apps were abusing
   // the lack of type checking previously and assigning random strings.
-  /** Palette color of the checkbox. */
+  /**
+   * Palette color of the checkbox. This API is supported in M2 themes only, it has no effect in M3
+   * themes. For information on applying color variants in M3, see
+   * https://material.angular.io/guide/theming#using-component-color-variants
+   */
   @Input() color: string | undefined;
 
   /**