feat(material/button): Add support for showing a progress indicator inside the button

Add a new API, testing API, and docs for allowing progress indicators to be projected into a button and have them shown in an accessible manner

Fixes #13667

Author: jermowery

goldens/material/button/index.api.md

@@ -33,7 +33,7 @@ export class MatButton extends MatButtonBase {
     set appearance(value: MatButtonAppearance | '');
     setAppearance(appearance: MatButtonAppearance): void;
     // (undocumented)
-    static ɵcmp: i0.ɵɵComponentDeclaration<MatButton, "    button[matButton], a[matButton], button[mat-button], button[mat-raised-button],    button[mat-flat-button], button[mat-stroked-button], a[mat-button], a[mat-raised-button],    a[mat-flat-button], a[mat-stroked-button]  ", ["matButton", "matAnchor"], { "appearance": { "alias": "matButton"; "required": false; }; }, {}, never, [".material-icons:not([iconPositionEnd]), mat-icon:not([iconPositionEnd]), [matButtonIcon]:not([iconPositionEnd])", "*", ".material-icons[iconPositionEnd], mat-icon[iconPositionEnd], [matButtonIcon][iconPositionEnd]"], true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<MatButton, "    button[matButton], a[matButton], button[mat-button], button[mat-raised-button],    button[mat-flat-button], button[mat-stroked-button], a[mat-button], a[mat-raised-button],    a[mat-flat-button], a[mat-stroked-button]  ", ["matButton", "matAnchor"], { "appearance": { "alias": "matButton"; "required": false; }; }, {}, never, [".material-icons:not([iconPositionEnd]), mat-icon:not([iconPositionEnd]), [matButtonIcon]:not([iconPositionEnd])", "*", ".material-icons[iconPositionEnd], mat-icon[iconPositionEnd], [matButtonIcon][iconPositionEnd]", "[progressIndicator]"], true, never>;
     // (undocumented)
     static ɵfac: i0.ɵɵFactoryDeclaration<MatButton, never>;
 }
@@ -74,7 +74,7 @@ export class MatFabButton extends MatButtonBase {
     // (undocumented)
     static ngAcceptInputType_extended: unknown;
     // (undocumented)
-    static ɵcmp: i0.ɵɵComponentDeclaration<MatFabButton, "button[mat-fab], a[mat-fab], button[matFab], a[matFab]", ["matButton", "matAnchor"], { "extended": { "alias": "extended"; "required": false; }; }, {}, never, [".material-icons:not([iconPositionEnd]), mat-icon:not([iconPositionEnd]), [matButtonIcon]:not([iconPositionEnd])", "*", ".material-icons[iconPositionEnd], mat-icon[iconPositionEnd], [matButtonIcon][iconPositionEnd]"], true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<MatFabButton, "button[mat-fab], a[mat-fab], button[matFab], a[matFab]", ["matButton", "matAnchor"], { "extended": { "alias": "extended"; "required": false; }; }, {}, never, [".material-icons:not([iconPositionEnd]), mat-icon:not([iconPositionEnd]), [matButtonIcon]:not([iconPositionEnd])", "*", ".material-icons[iconPositionEnd], mat-icon[iconPositionEnd], [matButtonIcon][iconPositionEnd]", "[progressIndicator]"], true, never>;
     // (undocumented)
     static ɵfac: i0.ɵɵFactoryDeclaration<MatFabButton, never>;
 }
@@ -94,7 +94,7 @@ export type MatIconAnchor = MatIconButton;
 export class MatIconButton extends MatButtonBase {
     constructor(...args: unknown[]);
     // (undocumented)
-    static ɵcmp: i0.ɵɵComponentDeclaration<MatIconButton, "button[mat-icon-button], a[mat-icon-button], button[matIconButton], a[matIconButton]", ["matButton", "matAnchor"], {}, {}, never, ["*"], true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<MatIconButton, "button[mat-icon-button], a[mat-icon-button], button[matIconButton], a[matIconButton]", ["matButton", "matAnchor"], {}, {}, never, ["*", "[progressIndicator]"], true, never>;
     // (undocumented)
     static ɵfac: i0.ɵɵFactoryDeclaration<MatIconButton, never>;
 }
@@ -111,7 +111,7 @@ export class MatMiniFabButton extends MatButtonBase {
     // (undocumented)
     _isFab: boolean;
     // (undocumented)
-    static ɵcmp: i0.ɵɵComponentDeclaration<MatMiniFabButton, "button[mat-mini-fab], a[mat-mini-fab], button[matMiniFab], a[matMiniFab]", ["matButton", "matAnchor"], {}, {}, never, [".material-icons:not([iconPositionEnd]), mat-icon:not([iconPositionEnd]), [matButtonIcon]:not([iconPositionEnd])", "*", ".material-icons[iconPositionEnd], mat-icon[iconPositionEnd], [matButtonIcon][iconPositionEnd]"], true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<MatMiniFabButton, "button[mat-mini-fab], a[mat-mini-fab], button[matMiniFab], a[matMiniFab]", ["matButton", "matAnchor"], {}, {}, never, [".material-icons:not([iconPositionEnd]), mat-icon:not([iconPositionEnd]), [matButtonIcon]:not([iconPositionEnd])", "*", ".material-icons[iconPositionEnd], mat-icon[iconPositionEnd], [matButtonIcon][iconPositionEnd]", "[progressIndicator]"], true, never>;
     // (undocumented)
     static ɵfac: i0.ɵɵFactoryDeclaration<MatMiniFabButton, never>;
 }

goldens/material/button/testing/index.api.md

@@ -42,6 +42,7 @@ export class MatButtonHarness extends ContentContainerComponentHarness {
     static hostSelector: string;
     isDisabled(): Promise<boolean>;
     isFocused(): Promise<boolean>;
+    isShowingProgress(): Promise<boolean>;
     static with<T extends MatButtonHarness>(this: ComponentHarnessConstructor<T>, options?: ButtonHarnessFilters): HarnessPredicate<T>;
 }
 

src/components-examples/material/button/BUILD.bazel

@@ -20,8 +20,10 @@ ng_project(
         "//src/cdk/testing/testbed",
         "//src/material/button",
         "//src/material/button/testing",
+        "//src/material/checkbox",
         "//src/material/divider",
         "//src/material/icon",
+        "//src/material/progress-spinner",
         "//src/material/tooltip",
     ],
 )

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

@@ -4,6 +4,16 @@
     <button matButton>Basic</button>
     <button matButton disabled>Disabled</button>
     <a matButton href="https://www.google.com/" target="_blank">Link</a>
+    <button matButton showProgress="true">
+      Progress
+      <mat-progress-spinner
+        progressIndicator
+        mode="indeterminate"
+        diameter="20"
+        aria-label="Loading"
+        tabindex=""
+      />
+    </button>
   </div>
 </section>
 <mat-divider/>
@@ -13,6 +23,16 @@
     <button matButton="elevated">Basic</button>
     <button matButton="elevated" disabled>Disabled</button>
     <a matButton="elevated" href="https://www.google.com/" target="_blank">Link</a>
+    <button matButton="elevated" showProgress="true">
+      Progress
+      <mat-progress-spinner
+        progressIndicator
+        mode="indeterminate"
+        diameter="20"
+        aria-label="Loading"
+        tabindex=""
+      />
+    </button>
   </div>
 </section>
 <mat-divider/>
@@ -22,6 +42,16 @@
     <button matButton="outlined">Basic</button>
     <button matButton="outlined" disabled>Disabled</button>
     <a matButton="outlined" href="https://www.google.com/" target="_blank">Link</a>
+    <button matButton="outlined" showProgress="true">
+      Progress
+      <mat-progress-spinner
+        progressIndicator
+        mode="indeterminate"
+        diameter="20"
+        aria-label="Loading"
+        tabindex=""
+      />
+    </button>
   </div>
 </section>
 <mat-divider/>
@@ -31,6 +61,16 @@
     <button matButton="filled">Basic</button>
     <button matButton="filled" disabled>Disabled</button>
     <a matButton="filled" href="https://www.google.com/" target="_blank">Link</a>
+    <button matButton="filled" showProgress="true">
+      Progress
+      <mat-progress-spinner
+        progressIndicator
+        mode="indeterminate"
+        diameter="20"
+        aria-label="Loading"
+        tabindex=""
+      />
+    </button>
   </div>
 </section>
 <mat-divider/>
@@ -40,6 +80,16 @@
     <button matButton="tonal" >Basic</button>
     <button matButton="tonal"  disabled>Disabled</button>
     <a matButton="tonal" href="https://www.google.com/" target="_blank">Link</a>
+    <button matButton="tonal" showProgress="true">
+      Progress
+      <mat-progress-spinner
+        progressIndicator
+        mode="indeterminate"
+        diameter="20"
+        aria-label="Loading"
+        tabindex=""
+      />
+    </button>
   </div>
 </section>
 <mat-divider/>
@@ -53,6 +103,16 @@
       <button matIconButton disabled aria-label="Example icon button with a open in new tab icon">
         <mat-icon>open_in_new</mat-icon>
       </button>
+      <button matIconButton showProgress="true" aria-label="Example icon button with a download icon">
+        <mat-icon>download</mat-icon>
+        <mat-progress-spinner
+          progressIndicator
+          mode="indeterminate"
+          diameter="20"
+          aria-label="Loading"
+          tabindex=""
+        />
+      </button>
     </div>
   </div>
 </section>
@@ -67,6 +127,16 @@
       <button matFab disabled aria-label="Example icon button with a heart icon">
         <mat-icon>favorite</mat-icon>
       </button>
+      <button matFab showProgress="true" aria-label="Example icon button with a skull icon">
+        <mat-icon>skull</mat-icon>
+        <mat-progress-spinner
+          progressIndicator
+          mode="indeterminate"
+          diameter="20"
+          aria-label="Loading"
+          tabindex=""
+        />
+      </button>
     </div>
   </div>
 </section>
@@ -81,6 +151,16 @@
       <button matMiniFab disabled aria-label="Example icon button with a home icon">
         <mat-icon>home</mat-icon>
       </button>
+      <button matMiniFab showProgress="true" aria-label="Example icon button with a wifi icon">
+        <mat-icon>wifi</mat-icon>
+        <mat-progress-spinner
+          progressIndicator
+          mode="indeterminate"
+          diameter="20"
+          aria-label="Loading"
+          tabindex=""
+        />
+      </button>
     </div>
   </div>
 </section>
@@ -101,6 +181,17 @@
         <mat-icon>favorite</mat-icon>
         Link
       </a>
+      <button matFab extended showProgress="true">
+        <mat-icon>favorite</mat-icon>
+        Progress
+        <mat-progress-spinner
+          progressIndicator
+          mode="indeterminate"
+          diameter="20"
+          aria-label="Loading"
+          tabindex=""
+        />
+      </button>
     </div>
   </div>
 </section>

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

@@ -2,6 +2,7 @@ import {Component} from '@angular/core';
 import {MatIconModule} from '@angular/material/icon';
 import {MatDividerModule} from '@angular/material/divider';
 import {MatButtonModule} from '@angular/material/button';
+import {MatProgressSpinner} from '@angular/material/progress-spinner';
 
 /**
  * @title Button overview
@@ -10,6 +11,6 @@ import {MatButtonModule} from '@angular/material/button';
   selector: 'button-overview-example',
   templateUrl: 'button-overview-example.html',
   styleUrl: 'button-overview-example.css',
-  imports: [MatButtonModule, MatDividerModule, MatIconModule],
+  imports: [MatButtonModule, MatDividerModule, MatIconModule, MatProgressSpinner],
 })
 export class ButtonOverviewExample {}

src/components-examples/material/button/button-progress-indicator/button-progress-indicator-example.html

@@ -0,0 +1,29 @@
+<section>
+  <mat-checkbox
+    (change)="toggleShowProgress()"
+  >
+    Show the progress indicator
+  </mat-checkbox>
+</section>
+<section>
+    <h3>Button with a MatProgressSpinner</h3>
+    <button matButton="outlined" [showProgress]="showProgress()">
+      Download
+      <mat-progress-spinner
+        progressIndicator
+        mode="indeterminate"
+        diameter="20"
+        aria-label="Loading"
+        tabindex=""
+      />
+    </button>
+</section>
+<section>
+    <h3>Button with a custom progress indicator</h3>
+    <button matButton="outlined" [showProgress]="showProgress()">
+      Download
+    <div progressIndicator role="progressbar" aria-valuemin="0" aria-valuemax="100">
+        Loading...
+    </div>
+    </button>
+</section>

src/components-examples/material/button/button-progress-indicator/button-progress-indicator-example.ts

@@ -0,0 +1,20 @@
+import {Component, signal} from '@angular/core';
+import {MatButton} from '@angular/material/button';
+import {MatCheckbox} from '@angular/material/checkbox';
+import {MatProgressSpinner} from '@angular/material/progress-spinner';
+
+/**
+ * @title Buttons with progress indicators
+ */
+@Component({
+  selector: 'button-progress-indicator-example',
+  templateUrl: 'button-progress-indicator-example.html',
+  imports: [MatButton, MatCheckbox, MatProgressSpinner],
+})
+export class ButtonProgressIndicatorExample {
+  protected readonly showProgress = signal(false);
+
+  protected toggleShowProgress() {
+    this.showProgress.update(show => !show);
+  }
+}

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

@@ -1,3 +1,4 @@
 export {ButtonOverviewExample} from './button-overview/button-overview-example';
 export {ButtonDisabledInteractiveExample} from './button-disabled-interactive/button-disabled-interactive-example';
 export {ButtonHarnessExample} from './button-harness/button-harness-example';
+export {ButtonProgressIndicatorExample} from './button-progress-indicator/button-progress-indicator-example';

src/dev-app/button/BUILD.bazel

@@ -15,6 +15,7 @@ ng_project(
         "//src/material/button",
         "//src/material/checkbox",
         "//src/material/icon",
+        "//src/material/progress-spinner",
         "//src/material/tooltip",
     ],
 )