Add docs for progress indicators with buttons

Author: jermowery

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/material/button/button.md

@@ -56,6 +56,11 @@ guard against such cases in your component.
 
 <!-- example(button-disabled-interactive) -->
 
+### Buttons with progress indicators
+An element with the `progressIndicator` attribute may be projected into the button element. When the `showProgress` input is `true` this element will be shown over the content of the button and the content of the button will be made invisible.
+
+<!-- example(button-progress-indicator) -->
+
 ### Accessibility
 Angular Material uses native `<button>` and `<a>` elements to ensure an accessible experience by
 default. A `<button>` element should be used for any interaction that _performs an action on the
@@ -82,3 +87,6 @@ information on using icons in buttons. Additionally, to be fully accessible the
 #### Toggle buttons
 [See the documentation for `MatButtonToggle`](https://material.angular.dev/components/button-toggle)
 for information on stateful toggle buttons.
+
+#### Buttons with progress indicators
+The element projected using the `progressIndicator` attribute must not be interactable. When using `MatProgressSpinner` set `tabindex=""` to remove the progress indicator for the tab order.

src/material/button/button.scss

@@ -4,6 +4,7 @@
 @use '../core/tokens/token-utils';
 @use '../core/focus-indicators/private' as focus-indicators-private;
 @use './m3-button';
+@use '../progress-spinner/progress-spinner-theme';
 
 $fallbacks: m3-button.get-tokens();