feat(material/stepper): add the ability to control the position of the header in a horizontal stepper

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

@@ -17,6 +17,7 @@ import {StepperHarnessExample} from './stepper-harness/stepper-harness-example';
 import {StepperIntlExample} from './stepper-intl/stepper-intl-example';
 import {StepperLazyContentExample} from './stepper-lazy-content/stepper-lazy-content-example';
 import {StepperResponsiveExample} from './stepper-responsive/stepper-responsive-example';
+import {StepperHeaderPositionExample} from './stepper-header-position/stepper-header-position-example';
 
 export {
   StepperEditableExample,
@@ -30,6 +31,7 @@ export {
   StepperVerticalExample,
   StepperLazyContentExample,
   StepperResponsiveExample,
+  StepperHeaderPositionExample,
 };
 
 const EXAMPLES = [
@@ -44,6 +46,7 @@ const EXAMPLES = [
   StepperVerticalExample,
   StepperLazyContentExample,
   StepperResponsiveExample,
+  StepperHeaderPositionExample,
 ];
 
 @NgModule({

src/components-examples/material/stepper/stepper-header-position/stepper-header-position-example.css

@@ -0,0 +1 @@
+/** No CSS for this example */

src/components-examples/material/stepper/stepper-header-position/stepper-header-position-example.html

@@ -0,0 +1,33 @@
+<mat-stepper headerPosition="bottom" #stepper>
+  <mat-step [stepControl]="firstFormGroup">
+    <form [formGroup]="firstFormGroup">
+      <ng-template matStepLabel>Fill out your name</ng-template>
+      <mat-form-field>
+        <input matInput placeholder="Last name, First name" formControlName="firstCtrl" required>
+      </mat-form-field>
+      <div>
+        <button mat-button matStepperNext>Next</button>
+      </div>
+    </form>
+  </mat-step>
+  <mat-step [stepControl]="secondFormGroup" optional>
+    <form [formGroup]="secondFormGroup">
+      <ng-template matStepLabel>Fill out your address</ng-template>
+      <mat-form-field>
+        <input matInput placeholder="Address" formControlName="secondCtrl" required>
+      </mat-form-field>
+      <div>
+        <button mat-button matStepperPrevious>Back</button>
+        <button mat-button matStepperNext>Next</button>
+      </div>
+    </form>
+  </mat-step>
+  <mat-step>
+    <ng-template matStepLabel>Done</ng-template>
+    You are now done.
+    <div>
+      <button mat-button matStepperPrevious>Back</button>
+      <button mat-button (click)="stepper.reset()">Reset</button>
+    </div>
+  </mat-step>
+</mat-stepper>

src/components-examples/material/stepper/stepper-header-position/stepper-header-position-example.ts

@@ -0,0 +1,26 @@
+import {Component, OnInit} from '@angular/core';
+import {FormBuilder, FormGroup, Validators} from '@angular/forms';
+
+/**
+ * @title Stepper header position
+ */
+@Component({
+  selector: 'stepper-header-position-example',
+  templateUrl: 'stepper-header-position-example.html',
+  styleUrls: ['stepper-header-position-example.css'],
+})
+export class StepperHeaderPositionExample implements OnInit {
+  firstFormGroup: FormGroup;
+  secondFormGroup: FormGroup;
+
+  constructor(private _formBuilder: FormBuilder) {}
+
+  ngOnInit() {
+    this.firstFormGroup = this._formBuilder.group({
+      firstCtrl: ['', Validators.required],
+    });
+    this.secondFormGroup = this._formBuilder.group({
+      secondCtrl: ['', Validators.required],
+    });
+  }
+}

src/material/stepper/stepper.html

@@ -1,6 +1,6 @@
 <ng-container [ngSwitch]="orientation">
   <!-- Horizontal stepper -->
-  <ng-container *ngSwitchCase="'horizontal'">
+  <div class="mat-horizontal-stepper-wrapper" *ngSwitchCase="'horizontal'">
     <div class="mat-horizontal-stepper-header-container">
       <ng-container *ngFor="let step of steps; let i = index; let isLast = last">
         <ng-container
@@ -21,7 +21,7 @@
         <ng-container [ngTemplateOutlet]="step.content"></ng-container>
       </div>
     </div>
-  </ng-container>
+  </div>
 
   <!-- Vertical stepper -->
   <ng-container *ngSwitchCase="'vertical'">

src/material/stepper/stepper.md

@@ -33,6 +33,13 @@ This behaviour is controlled by `labelPosition` property.
               "file": "stepper-label-position-bottom-example.html",
               "region": "label-position"}) -->
 
+#### Header position
+If you're using a horizontal stepper, you can control where the stepper's content is positioned
+using the `headerPosition` input. By default it's on top of the content, but it can also be placed
+under it.
+
+<!-- example(stepper-header-position) -->
+
 ### Stepper buttons
 There are two button directives to support navigation between different steps:
 `matStepperPrevious` and `matStepperNext`.

src/material/stepper/stepper.scss

@@ -16,6 +16,10 @@
   .mat-stepper-label-position-bottom & {
     align-items: flex-start;
   }
+
+  .mat-stepper-header-position-bottom & {
+    order: 1;
+  }
 }
 
 .mat-stepper-horizontal-line {
@@ -116,6 +120,11 @@
   }
 }
 
+.mat-horizontal-stepper-wrapper {
+  display: flex;
+  flex-direction: column;
+}
+
 .mat-horizontal-stepper-content {
   outline: 0;
 
@@ -132,6 +141,10 @@
 
   overflow: hidden;
   padding: 0 stepper-variables.$side-gap stepper-variables.$side-gap stepper-variables.$side-gap;
+
+  .mat-stepper-header-position-bottom & {
+    padding: stepper-variables.$side-gap stepper-variables.$side-gap 0 stepper-variables.$side-gap;
+  }
 }
 
 .mat-vertical-content-container {

src/material/stepper/stepper.spec.ts

@@ -1238,6 +1238,19 @@ describe('MatStepper', () => {
       expect(interactedSteps).toEqual([0, 1, 2]);
       subscription.unsubscribe();
     });
+
+    it('should set a class on the host if the header is positioned at the bottom', () => {
+      const fixture = createComponent(SimpleMatHorizontalStepperApp);
+      fixture.detectChanges();
+      const stepperHost = fixture.nativeElement.querySelector('.mat-stepper-horizontal');
+
+      expect(stepperHost.classList).not.toContain('mat-stepper-header-position-bottom');
+
+      fixture.componentInstance.headerPosition = 'bottom';
+      fixture.detectChanges();
+
+      expect(stepperHost.classList).toContain('mat-stepper-header-position-bottom');
+    });
   });
 
   describe('linear stepper with valid step', () => {
@@ -1815,7 +1828,10 @@ class MatHorizontalStepperWithErrorsApp implements OnInit {
 
 @Component({
   template: `
-    <mat-stepper [disableRipple]="disableRipple" [color]="stepperTheme">
+    <mat-stepper
+      [disableRipple]="disableRipple"
+      [color]="stepperTheme"
+      [headerPosition]="headerPosition">
       <mat-step>
         <ng-template matStepLabel>Step 1</ng-template>
         Content 1
@@ -1847,6 +1863,7 @@ class SimpleMatHorizontalStepperApp {
   disableRipple = false;
   stepperTheme: ThemePalette;
   secondStepTheme: ThemePalette;
+  headerPosition: string;
 }
 
 @Component({

src/material/stepper/stepper.ts

@@ -131,6 +131,7 @@ export class MatStep extends CdkStep implements ErrorStateMatcher, AfterContentI
       'orientation === "horizontal" && labelPosition == "end"',
     '[class.mat-stepper-label-position-bottom]':
       'orientation === "horizontal" && labelPosition == "bottom"',
+    '[class.mat-stepper-header-position-bottom]': 'headerPosition === "bottom"',
     '[attr.aria-orientation]': 'orientation',
     'role': 'tablist',
   },
@@ -171,6 +172,13 @@ export class MatStepper extends CdkStepper implements AfterContentInit {
   @Input()
   labelPosition: 'bottom' | 'end' = 'end';
 
+  /**
+   * Position of the stepper's header.
+   * Only applies in the `horizontal` orientation.
+   */
+  @Input()
+  headerPosition: 'top' | 'bottom' = 'top';
+
   /** Consumer-specified template-refs to be used to override the header icons. */
   _iconOverrides: Record<string, TemplateRef<MatStepperIconContext>> = {};
 

tools/public_api_guard/material/stepper.md

@@ -132,6 +132,7 @@ export class MatStepper extends CdkStepper implements AfterContentInit {
     readonly _animationDone: Subject<AnimationEvent_2>;
     color: ThemePalette;
     disableRipple: boolean;
+    headerPosition: 'top' | 'bottom';
     _iconOverrides: Record<string, TemplateRef<MatStepperIconContext>>;
     _icons: QueryList<MatStepperIcon>;
     labelPosition: 'bottom' | 'end';
@@ -143,7 +144,7 @@ export class MatStepper extends CdkStepper implements AfterContentInit {
     readonly steps: QueryList<MatStep>;
     _steps: QueryList<MatStep>;
     // (undocumented)
-    static ɵcmp: i0.ɵɵComponentDeclaration<MatStepper, "mat-stepper, mat-vertical-stepper, mat-horizontal-stepper, [matStepper]", ["matStepper", "matVerticalStepper", "matHorizontalStepper"], { "selectedIndex": "selectedIndex"; "disableRipple": "disableRipple"; "color": "color"; "labelPosition": "labelPosition"; }, { "animationDone": "animationDone"; }, ["_steps", "_icons"], never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<MatStepper, "mat-stepper, mat-vertical-stepper, mat-horizontal-stepper, [matStepper]", ["matStepper", "matVerticalStepper", "matHorizontalStepper"], { "selectedIndex": "selectedIndex"; "disableRipple": "disableRipple"; "color": "color"; "labelPosition": "labelPosition"; "headerPosition": "headerPosition"; }, { "animationDone": "animationDone"; }, ["_steps", "_icons"], never>;
     // (undocumented)
     static ɵfac: i0.ɵɵFactoryDeclaration<MatStepper, [{ optional: true; }, null, null]>;
 }