feat(stepper): allow for header icons to be customized

Currently users are locked into using the Material `create` and `done` icon for the step headers. These changes add the ability to customize the icons by providing an `ng-template` with an override.

Fixes #7384.

Author: crisbeto

src/lib/stepper/public-api.ts

@@ -11,4 +11,4 @@ export * from './step-label';
 export * from './stepper';
 export * from './stepper-button';
 export * from './step-header';
-
+export * from './stepper-icon';

src/lib/stepper/step-header.html

@@ -1,10 +1,19 @@
 <div class="mat-step-header-ripple" mat-ripple [matRippleTrigger]="_getHostElement()"></div>
-<div [class.mat-step-icon]="icon !== 'number' || selected"
-     [class.mat-step-icon-not-touched]="icon == 'number' && !selected"
-     [ngSwitch]="icon">
+<div [class.mat-step-icon]="state !== 'number' || selected"
+     [class.mat-step-icon-not-touched]="state == 'number' && !selected"
+     [ngSwitch]="state">
+
   <span *ngSwitchCase="'number'">{{index + 1}}</span>
-  <mat-icon *ngSwitchCase="'edit'">create</mat-icon>
-  <mat-icon *ngSwitchCase="'done'">done</mat-icon>
+
+  <ng-container *ngSwitchCase="'edit'" [ngSwitch]="!!(iconOverrides && iconOverrides.edit)">
+    <ng-container *ngSwitchCase="true" [ngTemplateOutlet]="iconOverrides.edit"></ng-container>
+    <mat-icon *ngSwitchDefault>create</mat-icon>
+  </ng-container>
+
+  <ng-container *ngSwitchCase="'done'" [ngSwitch]="!!(iconOverrides && iconOverrides.done)">
+    <ng-container *ngSwitchCase="true" [ngTemplateOutlet]="iconOverrides.done"></ng-container>
+    <mat-icon *ngSwitchDefault>done</mat-icon>
+  </ng-container>
 </div>
 <div class="mat-step-label"
      [class.mat-step-label-active]="active"

src/lib/stepper/step-header.ts

@@ -8,7 +8,15 @@
 
 import {FocusMonitor} from '@angular/cdk/a11y';
 import {coerceBooleanProperty, coerceNumberProperty} from '@angular/cdk/coercion';
-import {Component, Input, ViewEncapsulation, ElementRef, OnDestroy, Renderer2} from '@angular/core';
+import {
+  Component,
+  Input,
+  ViewEncapsulation,
+  ElementRef,
+  OnDestroy,
+  Renderer2,
+  TemplateRef,
+} from '@angular/core';
 import {MatStepLabel} from './step-label';
 
 
@@ -25,12 +33,15 @@ import {MatStepLabel} from './step-label';
   preserveWhitespaces: false,
 })
 export class MatStepHeader implements OnDestroy {
-  /** Icon for the given step. */
-  @Input() icon: string;
+  /** State of the given step. */
+  @Input() state: string;
 
   /** Label of the given step. */
   @Input() label: MatStepLabel | string;
 
+  /** Overrides for the header icons, passed in via the stepper. */
+  @Input() iconOverrides: {[key: string]: TemplateRef<any>};
+
   /** Index of the given step. */
   @Input()
   get index() { return this._index; }

src/lib/stepper/stepper-horizontal.html

@@ -8,11 +8,12 @@
                      [attr.aria-controls]="_getStepContentId(i)"
                      [attr.aria-selected]="selectedIndex == i"
                      [index]="i"
-                     [icon]="_getIndicatorType(i)"
+                     [state]="_getIndicatorType(i)"
                      [label]="step.stepLabel || step.label"
                      [selected]="selectedIndex === i"
                      [active]="step.completed || selectedIndex === i"
-                     [optional]="step.optional">
+                     [optional]="step.optional"
+                     [iconOverrides]="_iconOverrides">
     </mat-step-header>
     <div *ngIf="!isLast" class="mat-stepper-horizontal-line"></div>
   </ng-container>

src/lib/stepper/stepper-icon.ts

@@ -0,0 +1,22 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {Directive, Input, TemplateRef} from '@angular/core';
+
+/**
+ * Template to be used to override the icons inside the step header.
+ */
+@Directive({
+  selector: 'ng-template[matStepperIcon]',
+})
+export class MatStepperIcon {
+  /** Name of the icon to be overridden. */
+  @Input('matStepperIcon') name: 'edit' | 'done';
+
+  constructor(public templateRef: TemplateRef<any>) { }
+}

src/lib/stepper/stepper-module.ts

@@ -16,8 +16,9 @@ import {MatCommonModule, MatRippleModule} from '@angular/material/core';
 import {MatIconModule} from '@angular/material/icon';
 import {MatStepHeader} from './step-header';
 import {MatStepLabel} from './step-label';
-import {MatHorizontalStepper, MatStep, MatStepper, MatVerticalStepper} from './stepper';
 import {MatStepperNext, MatStepperPrevious} from './stepper-button';
+import {MatStepperIcon} from './stepper-icon';
+import {MatHorizontalStepper, MatStep, MatStepper, MatVerticalStepper} from './stepper';
 
 
 @NgModule({
@@ -40,9 +41,10 @@ import {MatStepperNext, MatStepperPrevious} from './stepper-button';
     MatStepper,
     MatStepperNext,
     MatStepperPrevious,
-    MatStepHeader
+    MatStepHeader,
+    MatStepperIcon,
   ],
   declarations: [MatHorizontalStepper, MatVerticalStepper, MatStep, MatStepLabel, MatStepper,
-    MatStepperNext, MatStepperPrevious, MatStepHeader],
+    MatStepperNext, MatStepperPrevious, MatStepHeader, MatStepperIcon],
 })
 export class MatStepperModule {}

src/lib/stepper/stepper-vertical.html

@@ -7,11 +7,12 @@
                    [attr.aria-controls]="_getStepContentId(i)"
                    [attr.aria-selected]="selectedIndex === i"
                    [index]="i"
-                   [icon]="_getIndicatorType(i)"
+                   [state]="_getIndicatorType(i)"
                    [label]="step.stepLabel || step.label"
                    [selected]="selectedIndex === i"
                    [active]="step.completed || selectedIndex === i"
-                   [optional]="step.optional">
+                   [optional]="step.optional"
+                   [iconOverrides]="_iconOverrides">
   </mat-step-header>
 
   <div class="mat-vertical-content-container" [class.mat-stepper-vertical-line]="!isLast">

src/lib/stepper/stepper.md

@@ -7,8 +7,8 @@ that drives a stepped workflow. Material stepper extends the CDK stepper and has
 styling.
 
 ### Stepper variants
-There are two stepper components: `mat-horizontal-stepper` and `mat-vertical-stepper`. They 
-can be used the same way. The only difference is the orientation of stepper. 
+There are two stepper components: `mat-horizontal-stepper` and `mat-vertical-stepper`. They
+can be used the same way. The only difference is the orientation of stepper.
 `mat-horizontal-stepper` selector can be used to create a horizontal stepper, and
 `mat-vertical-stepper` can be used to create a vertical stepper. `mat-step` components need to be
 placed inside either one of the two stepper components.
@@ -26,7 +26,7 @@ If a step's label is only text, then the `label` attribute can be used.
 </mat-vertical-stepper>
 ```
 
-For more complex labels, add a template with the `matStepLabel` directive inside the 
+For more complex labels, add a template with the `matStepLabel` directive inside the
 `mat-step`.
 ```html
 <mat-vertical-stepper>
@@ -49,22 +49,22 @@ There are two button directives to support navigation between different steps:
       <button mat-button matStepperNext>Next</button>
     </div>
   </mat-step>
-</mat-horizontal-stepper>  
+</mat-horizontal-stepper>
 ```
 
 ### Linear stepper
 The `linear` attribute can be set on `mat-horizontal-stepper` and `mat-vertical-stepper` to create
 a linear stepper that requires the user to complete previous steps before proceeding
 to following steps. For each `mat-step`, the `stepControl` attribute can be set to the top level
-`AbstractControl` that is used to check the validity of the step. 
+`AbstractControl` that is used to check the validity of the step.
 
 There are two possible approaches. One is using a single form for stepper, and the other is
 using a different form for each step.
 
 #### Using a single form
 When using a single form for the stepper, `matStepperPrevious` and `matStepperNext` have to be
 set to `type="button"` in order to prevent submission of the form before all steps
-are completed. 
+are completed.
 
 ```html
 <form [formGroup]="formGroup">
@@ -83,7 +83,7 @@ are completed.
       </div>
     </mat-step>
     ...
-  </mat-horizontal-stepper> 
+  </mat-horizontal-stepper>
 </form>
 ```
 
@@ -106,17 +106,36 @@ are completed.
 
 #### Optional step
 If completion of a step in linear stepper is not required, then the `optional` attribute can be set
-on `mat-step`. 
+on `mat-step`.
 
 #### Editable step
 By default, steps are editable, which means users can return to previously completed steps and
-edit their responses. `editable="true"` can be set on `mat-step` to change the default. 
+edit their responses. `editable="true"` can be set on `mat-step` to change the default
 
 #### Completed step
 By default, the `completed` attribute of a step returns `true` if the step is valid (in case of
 linear stepper) and the user has interacted with the step. The user, however, can also override
 this default `completed` behavior by setting the `completed` attribute as needed.
 
+#### Overriding icons
+By default, the step headers will use the `create` and `done` icons from the Material design icon
+set via `<md-icon>` elements. If you want to provide a different set of icons, you can do so
+by placing a `matStepperIcon` for each of the icons that you want to override:
+
+```html
+<mat-vertical-stepper>
+  <ng-template matStepperIcon="edit">
+    <custom-icon>edit</custom-icon>
+  </ng-template>
+
+  <ng-template matStepperIcon="done">
+    <custom-icon>done</custom-icon>
+  </ng-template>
+
+  <!-- Stepper steps go here -->
+</mat-vertical-stepper>
+```
+
 ### Keyboard interaction
 - <kbd>LEFT_ARROW</kbd>: Focuses the previous step header
 - <kbd>RIGHT_ARROW</kbd>: Focuses the next step header
@@ -131,4 +150,4 @@ is given `role="tab"`, and the content that can be expanded upon selection is gi
 `role="tabpanel"`. `aria-selected` attribute of step header and `aria-expanded` attribute of
 step content is automatically set based on step selection change.
 
-The stepper and each step should be given a meaningful label via `aria-label` or `aria-labelledby`.
+The stepper and each step should be given a meaningful label via `aria-label` or `aria-labelledby`.

src/lib/stepper/stepper.spec.ts

@@ -20,7 +20,8 @@ describe('MatHorizontalStepper', () => {
       imports: [MatStepperModule, NoopAnimationsModule, ReactiveFormsModule],
       declarations: [
         SimpleMatHorizontalStepperApp,
-        LinearMatHorizontalStepperApp
+        LinearMatHorizontalStepperApp,
+        IconOverridesStepper,
       ],
       providers: [
         {provide: Directionality, useFactory: () => ({value: dir})}
@@ -116,6 +117,41 @@ describe('MatHorizontalStepper', () => {
     });
   });
 
+  describe('icon overrides', () => {
+    let fixture: ComponentFixture<IconOverridesStepper>;
+
+    beforeEach(() => {
+      fixture = TestBed.createComponent(IconOverridesStepper);
+      fixture.detectChanges();
+    });
+
+    it('should allow for the `edit` icon to be overridden', () => {
+      const stepperDebugElement = fixture.debugElement.query(By.directive(MatStepper));
+      const stepperComponent: MatStepper = stepperDebugElement.componentInstance;
+
+      stepperComponent._steps.toArray()[0].editable = true;
+      stepperComponent.next();
+      fixture.detectChanges();
+
+      const header = stepperDebugElement.nativeElement.querySelector('mat-step-header');
+
+      expect(header.textContent).toContain('Custom edit');
+    });
+
+    it('should allow for the `done` icon to be overridden', () => {
+      const stepperDebugElement = fixture.debugElement.query(By.directive(MatStepper));
+      const stepperComponent: MatStepper = stepperDebugElement.componentInstance;
+
+      stepperComponent._steps.toArray()[0].editable = false;
+      stepperComponent.next();
+      fixture.detectChanges();
+
+      const header = stepperDebugElement.nativeElement.querySelector('mat-step-header');
+
+      expect(header.textContent).toContain('Custom done');
+    });
+  });
+
   describe('linear horizontal stepper', () => {
     let fixture: ComponentFixture<LinearMatHorizontalStepperApp>;
     let testComponent: LinearMatHorizontalStepperApp;
@@ -858,3 +894,17 @@ class LinearMatVerticalStepperApp {
     });
   }
 }
+
+@Component({
+  template: `
+    <mat-horizontal-stepper>
+      <ng-template matStepperIcon="edit">Custom edit</ng-template>
+      <ng-template matStepperIcon="done">Custom done</ng-template>
+
+      <mat-step>Content 1</mat-step>
+      <mat-step>Content 2</mat-step>
+      <mat-step>Content 3</mat-step>
+    </mat-horizontal-stepper>
+  `
+})
+class IconOverridesStepper {}

src/lib/stepper/stepper.ts

@@ -21,6 +21,8 @@ import {
   SkipSelf,
   ViewChildren,
   ViewEncapsulation,
+  TemplateRef,
+  AfterContentInit,
 } from '@angular/core';
 import {FormControl, FormGroupDirective, NgForm} from '@angular/forms';
 import {
@@ -31,6 +33,7 @@ import {
 } from '@angular/material/core';
 import {MatStepHeader} from './step-header';
 import {MatStepLabel} from './step-label';
+import {MatStepperIcon} from './stepper-icon';
 
 /** Workaround for https://github.com/angular/angular/issues/17849 */
 export const _MatStep = CdkStep;
@@ -75,15 +78,36 @@ export class MatStep extends _MatStep implements ErrorOptions {
   }
 }
 
+
 @Directive({
   selector: '[matStepper]'
 })
-export class MatStepper extends _MatStepper {
+export class MatStepper extends _MatStepper implements AfterContentInit {
   /** The list of step headers of the steps in the stepper. */
   @ViewChildren(MatStepHeader, {read: ElementRef}) _stepHeader: QueryList<ElementRef>;
 
   /** Steps that the stepper holds. */
   @ContentChildren(MatStep) _steps: QueryList<MatStep>;
+
+  /** Custom icon overrides passed in by the consumer. */
+  @ContentChildren(MatStepperIcon) _icons: QueryList<MatStepperIcon>;
+
+  /** Consumer-specified template-refs to be used to override the header icons. */
+  _iconOverrides: {[key: string]: TemplateRef<any>} = {};
+
+  ngAfterContentInit() {
+    const icons = this._icons.toArray();
+    const editOverride = icons.find(icon => icon.name === 'edit');
+    const doneOverride = icons.find(icon => icon.name === 'done');
+
+    if (editOverride) {
+      this._iconOverrides.edit = editOverride.templateRef;
+    }
+
+    if (doneOverride) {
+      this._iconOverrides.done = doneOverride.templateRef;
+    }
+  }
 }
 
 @Component({