docs: document button-toggle-group usage with forms (#21879)

Fixes #21774

Author: AlexElin

src/components-examples/material/button-toggle/button-toggle-forms/button-toggle-forms-example.html

@@ -0,0 +1,20 @@
+<section>
+  <h4>Button Toggle inside of a Template-driven form</h4>
+  <mat-button-toggle-group [(ngModel)]="fontStyle" aria-label="Font Style">
+    <mat-button-toggle value="bold">Bold</mat-button-toggle>
+    <mat-button-toggle value="italic">Italic</mat-button-toggle>
+    <mat-button-toggle value="underline">Underline</mat-button-toggle>
+  </mat-button-toggle-group>
+  <p>Chosen value is {{fontStyle}}</p>
+</section>
+
+<section>
+  <h4>Button Toggle inside of a Reactive form</h4>
+  <mat-button-toggle-group [formControl]="fontStyleControl" aria-label="Font Style">
+    <mat-button-toggle value="bold">Bold</mat-button-toggle>
+    <mat-button-toggle value="italic">Italic</mat-button-toggle>
+    <mat-button-toggle value="underline">Underline</mat-button-toggle>
+  </mat-button-toggle-group>
+  <p>Chosen value is {{fontStyleControl.value}}</p>
+</section>
+

src/components-examples/material/button-toggle/button-toggle-forms/button-toggle-forms-example.ts

@@ -0,0 +1,14 @@
+import {Component} from '@angular/core';
+import {FormControl} from '@angular/forms';
+
+/**
+ * @title Button-toggles with forms
+ */
+@Component({
+  selector: 'button-toggle-forms-example',
+  templateUrl: 'button-toggle-forms-example.html',
+})
+export class ButtonToggleFormsExample {
+  fontStyleControl = new FormControl();
+  fontStyle?: string;
+}

src/components-examples/material/button-toggle/index.ts

@@ -1,4 +1,5 @@
 import {NgModule} from '@angular/core';
+import {FormsModule, ReactiveFormsModule} from '@angular/forms';
 import {MatButtonToggleModule} from '@angular/material/button-toggle';
 import {MatIconModule} from '@angular/material/icon';
 import {
@@ -9,25 +10,30 @@ import {
 } from './button-toggle-exclusive/button-toggle-exclusive-example';
 import {ButtonToggleOverviewExample} from './button-toggle-overview/button-toggle-overview-example';
 import {ButtonToggleHarnessExample} from './button-toggle-harness/button-toggle-harness-example';
+import {ButtonToggleFormsExample} from './button-toggle-forms/button-toggle-forms-example';
 
 export {
   ButtonToggleAppearanceExample,
   ButtonToggleExclusiveExample,
   ButtonToggleOverviewExample,
   ButtonToggleHarnessExample,
+  ButtonToggleFormsExample,
 };
 
 const EXAMPLES = [
   ButtonToggleAppearanceExample,
   ButtonToggleExclusiveExample,
   ButtonToggleOverviewExample,
   ButtonToggleHarnessExample,
+  ButtonToggleFormsExample,
 ];
 
 @NgModule({
   imports: [
+    FormsModule,
     MatButtonToggleModule,
     MatIconModule,
+    ReactiveFormsModule,
   ],
   declarations: EXAMPLES,
   exports: EXAMPLES,

src/material/button-toggle/button-toggle.md

@@ -22,6 +22,10 @@ be configured globally using the `MAT_BUTTON_TOGGLE_DEFAULT_OPTIONS` injection t
 
 <!-- example(button-toggle-appearance) -->
 
+### Use with `@angular/forms`
+`<mat-button-toggle-group>` is compatible with `@angular/forms` and supports both `FormsModule`
+and `ReactiveFormsModule`.
+
 ### Accessibility
 The button-toggles internally use native `button` elements with `aria-pressed` to convey
 their toggled state. The button-toggle-group surrounding the individual buttons applies